c_api.h File Reference

a C style API of rabit. More...

#include <stdio.h>

Go to the source code of this file.

Macros
#define	RABIT_EXTERN_C
#define	RABIT_DLL   RABIT_EXTERN_C __attribute__ ((visibility ("default")))

Typedefs
typedef unsigned long	rbt_ulong
	rabit unsigned long type

Functions
RABIT_DLL bool	RabitInit (int argc, char *argv[])
	initialize the rabit module, call this once before using anything The additional arguments is not necessary. Usually rabit will detect settings from environment variables.
RABIT_DLL int	RabitFinalize (void)
	finalize the rabit engine, call this function after you finished all jobs.
RABIT_DLL int	RabitGetRingPrevRank (void)
	get rank of previous process in ring topology
RABIT_DLL int	RabitGetRank (void)
	get rank of current process
RABIT_DLL int	RabitGetWorldSize (void)
	get total number of process
RABIT_DLL int	RabitIsDistributed (void)
	get rank of current process
RABIT_DLL int	RabitTrackerPrint (const char *msg)
	print the msg to the tracker, this function can be used to communicate the information of the progress to the user who monitors the tracker
RABIT_DLL void	RabitGetProcessorName (char *out_name, rbt_ulong *out_len, rbt_ulong max_len)
	get name of processor
RABIT_DLL int	RabitBroadcast (void *sendrecv_data, rbt_ulong size, int root)
	broadcast an memory region to all others from root
RABIT_DLL int	RabitAllgather (void *sendrecvbuf, size_t total_size, size_t beginIndex, size_t size_node_slice, size_t size_prev_slice, int enum_dtype)
	Allgather function, each node have a segment of data in the ring of sendrecvbuf, the data provided by current node k is [slice_begin, slice_end), the next node's segment must start with slice_end after the call of Allgather, sendrecvbuf_ contains all the contents including all segments use a ring based algorithm.
RABIT_DLL int	RabitAllreduce (void *sendrecvbuf, size_t count, int enum_dtype, int enum_op, void(*prepare_fun)(void *arg), void *prepare_arg)
	perform in-place allreduce, on sendrecvbuf this function is NOT thread-safe
RABIT_DLL int	RabitVersionNumber (void)
RABIT_DLL int	RabitLinkTag (void)
	a Dummy function, used to cause force link of C API into the DLL.

Detailed Description

a C style API of rabit.

Copyright by Contributors

Author

Tianqi Chen

Function Documentation

RabitAllgather()

RABIT_DLL int RabitAllgather	(	void *	sendrecvbuf,
		size_t	total_size,
		size_t	beginIndex,
		size_t	size_node_slice,
		size_t	size_prev_slice,
		int	enum_dtype
	)

Allgather function, each node have a segment of data in the ring of sendrecvbuf, the data provided by current node k is [slice_begin, slice_end), the next node's segment must start with slice_end after the call of Allgather, sendrecvbuf_ contains all the contents including all segments use a ring based algorithm.

Parameters

sendrecvbuf	buffer for both sending and receiving data, it is a ring conceptually
total_size	total size of data to be gathered
beginIndex	beginning of the current slice in sendrecvbuf of type enum_dtype
size_node_slice	size of the current node slice
size_prev_slice	size of the previous slice i.e. slice of node (rank - 1) % world_size
enum_dtype	the enumeration of data type, see rabit::engine::mpi::DataType in engine.h of rabit include

Returns

this function can return kSuccess, kSockError, kGetExcept, see ReturnType for details

See also

ReturnType

RabitAllreduce()

RABIT_DLL int RabitAllreduce	(	void *	sendrecvbuf,
		size_t	count,
		int	enum_dtype,
		int	enum_op,
		void(*)(void *arg)	prepare_fun,
		void *	prepare_arg
	)

perform in-place allreduce, on sendrecvbuf this function is NOT thread-safe

Example Usage: the following code gives sum of 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
enum_dtype	the enumeration of data type, see rabit::engine::mpi::DataType in engine.h of rabit include
enum_op	the enumeration of operation type, see rabit::engine::mpi::OpType in engine.h of rabit
prepare_fun	Lazy preprocessing function, if it is not NULL, prepare_fun(prepare_arg) will be called by the function before performing Allreduce, 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 passed into the lazy preprocessing function

RabitBroadcast()

RABIT_DLL int RabitBroadcast	(	void *	sendrecv_data,
		rbt_ulong	size,
		int	root
	)

broadcast an memory region to all others from root

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

Parameters

sendrecv_data	the pointer to send or receive buffer,
size	the size of the data
root	the root of process

RabitFinalize()

RABIT_DLL int RabitFinalize

(

void

)

finalize the rabit engine, call this function after you finished all jobs.

Returns

true if rabit is initialized successfully otherwise false

RabitGetProcessorName()

RABIT_DLL void RabitGetProcessorName	(	char *	out_name,
		rbt_ulong *	out_len,
		rbt_ulong	max_len
	)

get name of processor

Parameters

out_name	hold output string
out_len	hold length of output string
max_len	maximum buffer length of input

RabitGetRank()

RABIT_DLL int RabitGetRank

(

void

)

get rank of current process

Returns

rank number of worker

RabitGetRingPrevRank()

RABIT_DLL int RabitGetRingPrevRank

(

void

)

get rank of previous process in ring topology

Returns

rank number of worker

RabitGetWorldSize()

RABIT_DLL int RabitGetWorldSize

(

void

)

get total number of process

Returns

total world size

RabitInit()

RABIT_DLL bool RabitInit	(	int	argc,
		char *	argv[]
	)

initialize the rabit module, call this once before using anything The additional arguments is not necessary. Usually rabit will detect settings from environment variables.

Parameters

argc	number of arguments in argv
argv	the array of input arguments

Returns

true if rabit is initialized successfully otherwise false

RabitIsDistributed()

RABIT_DLL int RabitIsDistributed

(

void

)

get rank of current process

Returns

if rabit is distributed

RabitLinkTag()

RABIT_DLL int RabitLinkTag

(

void

)

a Dummy function, used to cause force link of C API into the DLL.

\/\/force link rabit C API library.
static int must_link_rabit_ = RabitLinkTag();

Returns

a dummy integer.

RabitTrackerPrint()

RABIT_DLL int RabitTrackerPrint

(

const char *

msg

)

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

Parameters

msg	the message to be printed

RabitVersionNumber()

RABIT_DLL int RabitVersionNumber

(

void

)

Returns

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

rabit version number