C++ Library API of Rabit

This page contains document of Library API of rabit.

namespace rabit

rabit namespace

Typedefs

typedef dmlc::Stream Stream

defines stream used in rabit see definition of Stream in dmlc/io.h

typedef dmlc::Serializable Serializable

defines serializable objects used in rabit see definition of Serializable in dmlc/io.h

Functions

void Init(int argc, char *argv[])

initializes rabit, call this once at the beginning of your program

Parameters
  • argc -

    number of arguments in argv

  • argv -

    the array of input arguments

void Finalize(void)

finalizes the rabit engine, call this function after you finished with all the jobs

int GetRank(void)

gets rank of the current process

int GetWorldSize(void)

gets total number of processes

bool IsDistributed(void)

whether rabit env is in distributed mode

std::string GetProcessorName(void)

gets processor’s name

void TrackerPrint(const std::string &msg)

prints the msg to the tracker, this function can be used to communicate progress information to the user who monitors the tracker

Parameters
  • msg -

    the message to be printed

void TrackerPrintf(const char *fmt, ...)

prints the msg to the tracker, this function may not be available in very strict c++98 compilers, though it usually is. this function can be used to communicate progress information to the user who monitors the tracker

Parameters
  • fmt -

    the format string

void Broadcast(void *sendrecv_data, size_t size, int root)

broadcasts a memory region to every node from the root

Example: int a = 1; Broadcast(&a, sizeof(a), root);

Parameters
  • sendrecv_data -

    the pointer to the send/receive buffer,

  • size -

    the data size

  • root -

    the process root

template <typename DType>
void Broadcast(std::vector<DType> *sendrecv_data, int root)

broadcasts an std::vector<DType> to every node from root

Parameters
  • sendrecv_data -

    the pointer to send/receive vector, for the receiver, the vector does not need to be pre-allocated

  • root -

    the process root

Template Parameters
  • DType -

    the data type stored in the vector, has to be a simple data type that can be directly transmitted by sending the sizeof(DType)

void Broadcast(std::string *sendrecv_data, int root)

broadcasts a std::string to every node from the root

Parameters
  • sendrecv_data -

    the pointer to the send/receive buffer, for the receiver, the vector does not need to be pre-allocated

  • root -

    the process root

template <typename OP, typename DType>
void Allreduce(DType *sendrecvbuf, size_t count, void (*prepare_fun)(void *), void *prepare_arg, )

performs in-place Allreduce on sendrecvbuf this function is NOT thread-safe

Example Usage: the following code does an Allreduce and outputs the sum as the result 

vector<int> data(10);
...
Allreduce<op::Sum>(&data[0], data.size());
...

Parameters
  • sendrecvbuf -

    buffer for both sending and receiving data

  • count -

    number of elements to be reduced

  • prepare_fun -

    Lazy preprocessing function, if it is not NULL, prepare_fun(prepare_arg) will be called by the function before performing Allreduce in order to initialize the data in sendrecvbuf. If the result of Allreduce can be recovered directly, then prepare_func will NOT be called

  • prepare_arg -

    argument used to pass into the lazy preprocessing function

Template Parameters
  • OP -

    see namespace op, reduce operator

  • DType -

    data type

template <typename OP, typename DType>
void Allreduce(DType *sendrecvbuf, size_t count, std::function<void()> prepare_fun)

performs in-place Allreduce, on sendrecvbuf with a prepare function specified by a lambda function

Example Usage: 

// the following code does an Allreduce and outputs the sum as the result
vector<int> data(10);
...
Allreduce<op::Sum>(&data[0], data.size(), [&]() {
                    for (int i = 0; i < 10; ++i) {
                      data[i] = i;
                    }
                   });
    ...
Parameters
  • sendrecvbuf -

    buffer for both sending and receiving data

  • count -

    number of elements to be reduced

  • prepare_fun -

    Lazy lambda preprocessing function, prepare_fun() will be invoked by the function before performing Allreduce in order to initialize the data in sendrecvbuf. If the result of Allreduce can be recovered directly, then prepare_func will NOT be called

Template Parameters
  • OP -

    see namespace op, reduce operator

  • DType -

    data type

int LoadCheckPoint(Serializable *global_model, Serializable *local_model)

loads the latest check point 

// Example usage code of LoadCheckPoint
int iter = rabit::LoadCheckPoint(&model);
if (iter == 0) model.InitParameters();
for (i = iter; i < max_iter; ++i) {
  // do many things, include allreduce
  rabit::CheckPoint(model);
}
Return
the version number of the check point loaded if returned version == 0, this means no model has been CheckPointed the p_model is not touched, users should do the necessary initialization by themselves
See
CheckPoint, VersionNumber
Parameters
  • global_model -

    pointer to the globally shared model/state when calling this function, the caller needs to guarantee that the global_model is the same in every node

  • local_model -

    pointer to the local model that is specific to the current node/rank this can be NULL when no local model is needed

void CheckPoint(const Serializable *global_model, const Serializable *local_model)

checkpoints the model, meaning a stage of execution has finished. every time we call check point, a version number will be increased by one

See
LoadCheckPoint, VersionNumber
Parameters
  • global_model -

    pointer to the globally shared model/state when calling this function, the caller needs to guarantee that the global_model is the same in every node

  • local_model -

    pointer to the local model that is specific to the current node/rank this can be NULL when no local state is needed NOTE: local_model requires explicit replication of the model for fault-tolerance, which will bring replication cost in the CheckPoint function. global_model does not need explicit replication. So, only CheckPoint with the global_model if possible

void LazyCheckPoint(const Serializable *global_model)

This function can be used to replace CheckPoint for global_model only, when certain condition is met (see detailed explanation).

This is a “lazy” checkpoint such that only the pointer to the global_model is remembered and no memory copy is taken. To use this function, the user MUST ensure that: The global_model must remain unchanged until the last call of Allreduce/Broadcast in the current version finishes. In other words, the global_model model can be changed only between the last call of Allreduce/Broadcast and LazyCheckPoint, both in the same version

For example, suppose the calling sequence is: LazyCheckPoint, code1, Allreduce, code2, Broadcast, code3, LazyCheckPoint/(or can be CheckPoint)

Then the user MUST only change the global_model in code3.

The use of LazyCheckPoint instead of CheckPoint will improve the efficiency of the program.

See
LoadCheckPoint, CheckPoint, VersionNumber
Parameters
  • global_model -

    pointer to the globally shared model/state when calling this function, the caller needs to guarantee that the global_model is the same in every node

int VersionNumber(void)

Return
version number of the current stored model, which means how many calls to CheckPoint we made so far
See
LoadCheckPoint, CheckPoint

template <typename DType, void(*)(DType &dst, const DType &src) freduce>
class Reducer
#include <rabit.h>

template class to make customized reduce and all reduce easy Do not use reducer directly in the function you call Finalize, because the destructor can execute after Finalize

Template Parameters
  • DType -

    data type that to be reduced

  • freduce -

    the customized reduction function DType must be a struct, with no pointer

template <typename DType>
class SerializeReducer
#include <rabit.h>

template class to make customized reduce, this class defines complex reducer handles all the data structure that can be serialized/deserialized into fixed size buffer Do not use reducer directly in the function you call Finalize, because the destructor can execute after Finalize

Template Parameters
  • DType -

    data type that to be reduced, DType must contain the following functions:

  • freduce -

    the customized reduction function (1) Save(IStream &fs) (2) Load(IStream &fs) (3) Reduce(const DType &src, size_t max_nbyte)

namespace op

reduction operators namespace

class Max
#include <rabit.h>

maximum reduction operator

class Min
#include <rabit.h>

minimum reduction operator

class Sum
#include <rabit.h>

sum reduction operator

class BitOR
#include <rabit.h>

bitwise OR reduction operator