API document

API document

Multiverso environment

Header file: #include <multiverso.h>

1. MV_Init -- Init the Multiverso environment

• API: void MV_Init(int* argc, char* argv[])
• Argument: argc: pointer to number of arguments;
  argv: Argument vector

2. MV_Shutdown -- Terminates Multiverso execution environment

• API: void MV_Shutdown()

3. MV_Rank -- Get the rank of the calling process of current job

• API: int MV_Rank()
• Return value: rank of the calling process

4. MV_Size -- Get the number of processes of current job

• API: int MV_Size()
• Return value: number of processes of current job

5. MV_NumWorkers -- Get the number of workers

• API: int MV_NumWorkers()
• Return value: number of workers

6. MV_NumServers -- Get the number of servers

• API: int MV_NumServers()
• Return value: number of servers

7. MV_WorkerId -- Get the worker id of current process

• API: int MV_WorkerId()
• Return value: worker id of current node, -1 if there is no worker in current process

8. MV_ServerId -- Get the server id of current process

• API: int MV_ServerId()
• Return value: server id of current node, -1 if there is no server in current process
• Note: Each Multiverso job contains several processes, running in a group of machines. Each process has a unique id(MV_Rank), ranging from 0 to N-1. N is the number of processes (MV_Size). Each process may has a role, which can be either a worker(MV_WorkerId, from 0 to MV_NumWorkers-1), or a server(MV_Serverid, from 0 to MV_NumServers-1) or both.

9. MV_SetFlag -- Set the flag in Multiverso

• API: void MV_SetFlag<T>(const std::string& key, const T& value)

• Argument: key: name of the flag; value: value (type T) of the flag

• Note: There are two ways to set flag in Multiverso. The first one is using MV_SetFlag before MV_Init. (The MV_SetFlag must be called before MV_Init.) The second is setting in the argv argument of MV_Init. For example, set the flag in command line -sync=true and pass the command line arguments to MV_Init.

• Multiverso flags

  Name	Type	Description	Valid value
  sync	bool	Running Multiverso in Sync mode or Async mode	true for sync mode; false(default) for async mode
  updater	string	The updater used for server update	"simple"(default, just add what user pushes) / "sgd" / "momentum_sgd" / adagrad" / ...
  omp_threads	int	Number of threads used for server update	positive integer

10. MV_CreateTable Create table in Multiverso

• API: template typename OptionType::WorkerTableType* CreateTable(const OptionType& option)

• Argument: option:

• Return value: handler for table access. See Table API

• Note: There may have several kinds of tables in Multiverso. The type is specified by using different type of TableOption. The function will return ArrayTable if the argument is ArrayTableOption, or return MatrixTable if the argument if MatrixTableOption.

• Example:

  • Create a distributed shared array table,

      ArrayTableOption option; 
      option.size = 100; 
      auto table = MV_CreateTable(option);
    

  • Create a distributed shared matrix table,

      MatrixTableOption option; 
      option.num_rows = 10; option.num_cols = 20; 
      auto table = MV_CreateTable(option);
    

Table

ArrayTable

ArrayTable is a distributed shared array within workers and servers.

header file: #include <multiverso/table/array_table.h>

template <typename T>
class ArrayTable

MatrixTable

MatrixTable is a distributed shared matrix within workers and servers.

header file: #include <multiverso/table/matrix_table.h>

template <typename T>
class MatrixTable

API

1. Create -- Create a table handler for use

• ArrayTable Example:

      ArrayTableOption option;
      option.size = 1000;
      ArrayWorker<int>* table = MV_CreateTable(option);
  

• MatrixTable Example:

      MatrixTableOption option;
      option.num_rows = 100;
      option.num_cols = 10;
      MatrixWorker<int>* table = MV_CreateTable(option);
  

2. Get -- Get the latest parameters from server

• API: void Get(T* data, size_t size)
• Argument: a user-allocated array.
• Note: the request is sync(blocking) call. When the call finishes, the array represented by data stores the latest parameters.

3. GetAsync -- Get the latest parameters from server, async version

• API: int GetAsync(T* data, size_t size)
• Argument: a user-allocated array.
• Return: handle of the request.
• Note: the request is asynchonous. Call Wait(handle) to make sure the request is finished

4. Add -- Add the update to server

• API: void Add(T* data, size_t size)
• Argument: a user-allocated array which stores the delta to be updated
• Note: the request is sync(blocking) call. When the call finishes, the array represented by data is updated in the parameter server.

5. AddAsync -- Add the update to server, async version.

• API: int AddAsync(T* data, size_t size)
• Argument: a user-allocated array.
• Return: handle of the request.
• Note: the request is asynchonous. Call Wait(handle) to make sure the request is finished

6. Wait -- Wait(block current thread) until the asynchronous request finished.

• API: void Wait(int handle)
• Argument: request handle which is returned by GetAsync or AddAsync