Initialization, communicators, and memory#

Defines

WHOLEMEMORY_RETURN_ON_FAIL(X)#
WHOLEMEMORY_SPILT_NO_COLOR#
WHOLEMEMORY_UNIQUE_ID_BYTES#

Typedefs

typedef struct wholememory_comm_ *wholememory_comm_t#

Opaque handle to communicator.

An Opaque handle to communicator

typedef struct wholememory_handle_ *wholememory_handle_t#

Opaque handle to WholeMemory.

An Opaque handle to WholeMemory

Enums

enum wholememory_error_code_t#

WholeMemory Error Code definition.

Defines error code of WholeMemory library.

Values:

enumerator WHOLEMEMORY_SUCCESS#

success

enumerator WHOLEMEMORY_UNKNOW_ERROR#

unknown error

enumerator WHOLEMEMORY_NOT_IMPLEMENTED#

method is not implemented

enumerator WHOLEMEMORY_LOGIC_ERROR#

logic error

enumerator WHOLEMEMORY_CUDA_ERROR#

CUDA error

enumerator WHOLEMEMORY_COMMUNICATION_ERROR#

communication error

enumerator WHOLEMEMORY_INVALID_INPUT#

input is invalid, e.g. nullptr

enumerator WHOLEMEMORY_INVALID_VALUE#

input value is invalid

enumerator WHOLEMEMORY_OUT_OF_MEMORY#

out of memory

enumerator WHOLEMEMORY_NOT_SUPPORTED#

not supported

enumerator WHOLEMEMORY_SYSTEM_ERROR#

system error>

enum wholememory_memory_type_t#

Memory Type of WholeMemory.

Memory Type is the Memory Address Mapping Type of WholeMemory

Values:

enumerator WHOLEMEMORY_MT_NONE#

Not defined.

enumerator WHOLEMEMORY_MT_CONTINUOUS#

Memory from all ranks are mapped in continuous address space

enumerator WHOLEMEMORY_MT_CHUNKED#

Memory from all ranks are mapped in chunked address space

enumerator WHOLEMEMORY_MT_DISTRIBUTED#

Memory from other ranks are not mapped.

enumerator WHOLEMEMORY_MT_HIERARCHY#

Memory from other ranks are mapped in hierarchy address space

enum wholememory_memory_location_t#

Memory Location of WholeMemory.

Memory Location of WholeMemory can be host or device.

Values:

enumerator WHOLEMEMORY_ML_NONE#

Not defined

enumerator WHOLEMEMORY_ML_DEVICE#

Device Memory

enumerator WHOLEMEMORY_ML_HOST#

Host Memory

enum wholememory_distributed_backend_t#

Values:

enumerator WHOLEMEMORY_DB_NONE#

Not defined

enumerator WHOLEMEMORY_DB_NCCL#
enumerator WHOLEMEMORY_DB_NVSHMEM#
enum LogLevel#

Values:

enumerator LEVEL_FATAL#

Fatal

enumerator LEVEL_ERROR#

Error

enumerator LEVEL_WARN#

Warn

enumerator LEVEL_INFO#

Info

enumerator LEVEL_DEBUG#

Debug

enumerator LEVEL_TRACE#

Trace

Functions

wholememory_error_code_t wholememory_init(
unsigned int flags,
LogLevel log_level = LEVEL_INFO
)#

Initialize WholeMemory library

Parameters:

  • flags – : reserved should be 0

  • log_level – : wholememory log level, the default level is “info”

Returns:

: wholememory_error_code_t

wholememory_error_code_t wholememory_finalize()#

Finalize WholeMemory library

Returns:

: wholememory_error_code_t

wholememory_error_code_t wholememory_create_unique_id(
wholememory_unique_id_t *unique_id
)#

Create UniqueID for WholeMemory Communicator

Parameters:

unique_id – : returned UniqueID

Returns:

: wholememory_error_code_t

wholememory_error_code_t wholememory_create_communicator(
wholememory_comm_t *comm,
wholememory_unique_id_t unique_id,
int rank,
int size
)#

Create WholeMemory Communicator

Parameters:

  • comm – : returned WholeMemory Communicator

  • unique_id – : UniqueID

  • rank – : rank of this process.

  • size – : number of processes in this Communicator

Returns:

: wholememory_error_code_t

wholememory_error_code_t wholememory_split_communicator(
wholememory_comm_t *new_comm,
wholememory_comm_t comm,
int color,
int key
)#

Split WholeMemory Communicator

Parameters:

  • new_comm – returned the splited wholeMemory Communicator

  • comm – WholeMemory Communicator to split

  • color – color value to split communicator,Ranks which pass the same color value will be part of the same group; color must be a non-negative value. If it is passed as WHOLEMEMORY_SPLIT_NOCOLOR, it means that the rank will not be part of any group, therefore returning NULL as newcomm.

  • key – key value to split communicator,the value of key will determine the rank order, and the smaller key means the smaller rank in new communicator. If keys are equal between ranks, then the rank in the original communicator will be used to order ranks.

Returns:

: wholememory_error_code_t

wholememory_error_code_t wholememory_destroy_communicator(
wholememory_comm_t comm
)#

Destroy WholeMemory Communicator

Parameters:

comm – : WholeMemory Communicator to destroy

Returns:

: wholememory_error_code_t

wholememory_error_code_t wholememory_communicator_support_type_location(
wholememory_comm_t comm,
wholememory_memory_type_t memory_type,
wholememory_memory_location_t memory_location
)#

Check if combination of WholeMemory type and location is supported in the communicator

Parameters:

  • comm – : WholeMemory Communicator

  • memory_type – : WholeMemory type

  • memory_location – : WholeMemory Location

Returns:

WHOLEMEMORY_SUCCESS if supported else WHOLEMEMORY_NOT_SUPPORTED

wholememory_error_code_t wholememory_communicator_get_rank(
int *rank,
wholememory_comm_t comm
)#

Get the rank of current process in the WholeMemory Communicator

Parameters:

  • rank – : returned rank

  • comm – : WholeMemory Communicator

Returns:

: wholememory_error_code_t

wholememory_error_code_t wholememory_communicator_get_size(
int *size,
wholememory_comm_t comm
)#

Get the size of WholeMemory Communicator

Parameters:

  • size – : returned size

  • comm – : WholeMemory Communicator

Returns:

: wholememory_error_code_t

wholememory_error_code_t wholememory_communicator_get_local_size(
int *local_size,
wholememory_comm_t comm
)#

Get the local rank size of current process in the WholeMemory Communicator

Parameters:

  • local_size – : returned local rank size

  • comm – : WholeMemory Communicator

Returns:

: wholememory_error_code_t

wholememory_error_code_t wholememory_communicator_get_clique_info(
clique_info_t *clique_info,
wholememory_comm_t comm
)#

Get the clique info of WholeMemory Communicator

Parameters:

  • clique_info – : returned clique info

  • comm – : WholeMemory Communicator

Returns:

: wholememory_error_code_t

bool wholememory_communicator_is_bind_to_nvshmem(
wholememory_comm_t comm
)#
wholememory_error_code_t wholememory_communicator_set_distributed_backend(
wholememory_comm_t comm,
wholememory_distributed_backend_t distributed_backend
)#
wholememory_distributed_backend_t wholememory_communicator_get_distributed_backend(
wholememory_comm_t comm
)#
wholememory_error_code_t wholememory_communicator_barrier(
wholememory_comm_t comm
)#

Barrier on WholeMemory Communicator

Parameters:

comm – : WholeMemory Communicator

Returns:

: wholememory_error_code_t

wholememory_error_code_t wholememory_malloc(
wholememory_handle_t *wholememory_handle_ptr,
size_t total_size,
wholememory_comm_t comm,
wholememory_memory_type_t memory_type,
wholememory_memory_location_t memory_location,
size_t data_granularity,
size_t *rank_entry_partition = nullptr
)#

Malloc WholeMemory

Parameters:

  • wholememory_handle_ptr – : returned WholeMemory Handle

  • total_size – : total allocated size in bytes.

  • comm – : WholeMemory Communicator

  • memory_type – : WholeMemory type

  • memory_location – : memory location, host or device

  • data_granularity – : granularity size of data, which is guaranteed not to be partitioned.

  • rank_entry_partition – : entry count of each rank (size of entry equal to data_granularity)

Returns:

: wholememory_error_code_t

wholememory_error_code_t wholememory_free(
wholememory_handle_t wholememory_handle
)#

Free allocated WholeMemory Handle

Parameters:

wholememory_handle – : WholeMemory Handle to free

Returns:

: wholememory_error_code_t

wholememory_error_code_t wholememory_get_communicator(
wholememory_comm_t *comm,
wholememory_handle_t wholememory_handle
)#

Get underlying WholeMemory Communicator from WholeMemory Handle

Parameters:

  • comm – : returned WholeMemory Communicator

  • wholememory_handle – : WholeMemory Handle

Returns:

: wholememory_error_code_t

wholememory_error_code_t wholememory_get_local_communicator(
wholememory_comm_t *comm,
wholememory_handle_t wholememory_handle
)#

Get underlying Wholememory Local Communicator for “Hierarchy” memory type from WholeMemory Handle

Parameters:

  • comm – : returned Local WholeMemory Communicator

  • wholememory_handle – : WholeMemory Handle

Returns:

: wholememory_error_code_t

wholememory_error_code_t wholememory_get_cross_communicator(
wholememory_comm_t *comm,
wholememory_handle_t wholememory_handle
)#

Get underlying Wholememory Cross Communicator for “Hierarchy” memory type from WholeMemory Handle One comminicator includes all rank with a same local id from different nodes

Parameters:

  • comm – : returned Cross WholeMemory Communicator

  • wholememory_handle – : WholeMemory Handle

Returns:

: wholememory_error_code_t

wholememory_memory_type_t wholememory_get_memory_type(
wholememory_handle_t wholememory_handle
)#

Get WholeMemory Type

Parameters:

wholememory_handle – : WholeMemory Handle

Returns:

: WholeMemory Type

wholememory_memory_location_t wholememory_get_memory_location(
wholememory_handle_t wholememory_handle
)#

Get WholeMemory Location

Parameters:

wholememory_handle – : WholeMemory Handle

Returns:

: WholeMemory Location

wholememory_distributed_backend_t wholememory_get_distributed_backend(
wholememory_handle_t wholememory_handle
)#
size_t wholememory_get_total_size(
wholememory_handle_t wholememory_handle
)#

Get total size of WholeMemory

Parameters:

wholememory_handle – : WholeMemory Handle

Returns:

: total size

size_t wholememory_get_data_granularity(
wholememory_handle_t wholememory_handle
)#

Get data granularity of WholeMemory Handle

Parameters:

wholememory_handle – : WholeMemory Handle

Returns:

: data granularity size

wholememory_error_code_t wholememory_get_local_memory(
void **local_ptr,
size_t *local_size,
size_t *local_offset,
wholememory_handle_t wholememory_handle
)#

Get local memory from WholeMemory Handle of current rank, local memory has direct access to the memory. But local memory doesn’t have to be on local GPU.

Parameters:

  • local_ptr – : returned local memory pointer

  • local_size – : returned local memory size

  • local_offset – : returned local memory offset from WholeMemory

  • wholememory_handle – : WholeMemory Handle

Returns:

: wholememory_error_code_t

wholememory_error_code_t wholememory_get_local_size(
size_t *local_size,
wholememory_handle_t wholememory_handle
)#

Get local memory size from WholeMemory Handle of current rank

Parameters:

  • local_size – : returned local memory size

  • wholememory_handle – : WholeMemory Handle

Returns:

: wholememory_error_code_t

wholememory_error_code_t wholememory_get_local_offset(
size_t *local_offset,
wholememory_handle_t wholememory_handle
)#

Get local memory offset from WholeMemory Handle of current rank

Parameters:

  • local_offset – : returned local memory offset

  • wholememory_handle – : WholeMemory Handle

Returns:

: wholememory_error_code_t

wholememory_error_code_t wholememory_get_rank_memory(
void **rank_memory_ptr,
size_t *rank_memory_size,
size_t *rank_memory_offset,
int rank,
wholememory_handle_t wholememory_handle
)#

Get local memory of specified rank from WholeMemory Handle

Parameters:

  • rank_memory_ptr – : returned local memory pointer of specified rank

  • rank_memory_size – : returned local memory size of specified rank

  • rank_memory_offset – : returned local memory offset of specified rank from WholeMemory

  • rank – : rank specified

  • wholememory_handle – : WholeMemory Handle

Returns:

: wholememory_error_code_t

wholememory_error_code_t wholememory_equal_entry_partition_plan(
size_t *entry_per_rank,
size_t total_entry_count,
int world_size
)#

Get the equal partition plan WholeMemory uses by default

Parameters:

  • entry_per_rank – : returned entry count per rank

  • total_entry_count – : total entry count

  • world_size – : communicator world size

Returns:

: wholememory_error_code_t

wholememory_error_code_t wholememory_get_global_pointer(
void **global_ptr,
wholememory_handle_t wholememory_handle
)#

Get global memory pointer from WholeMemory Handle. Only Continuous memory type or Chunked Host memory has global pointer.

Parameters:

  • global_ptr – : returned pointer of WholeMemory

  • wholememory_handle – : WholeMemory Handle

Returns:

: wholememory_error_code_t

wholememory_error_code_t wholememory_get_global_reference(
wholememory_gref_t *wholememory_gref,
wholememory_handle_t wholememory_handle
)#

Get global reference from WholeMemory Handle WholeMemory global reference is common data structure for Continuous and Chunked Memory Types.

Parameters:

  • wholememory_gref – : returned WholeMemory global reference

  • wholememory_handle – : WholeMemory Handle

Returns:

: wholememory_error_code_t

wholememory_error_code_t wholememory_get_rank_partition_sizes(
size_t *rank_mem_sizes,
wholememory_handle_t wholememory_handle
)#

Get memory size of each rank from WholeMemory Handle

Parameters:

  • rank_mem_sizes – : returned memory size of each rank

  • wholememory_handle – : WholeMemory Handle

Returns:

: wholememory_error_code_t

wholememory_error_code_t wholememory_get_rank_partition_offsets(
size_t *rank_mem_offsets,
wholememory_handle_t wholememory_handle
)#

Get memory offset of each rank from WholeMemory Handle

Parameters:

  • rank_mem_offsets – : returned memory offset of each rank

  • wholememory_handle – : WholeMemory Handle

Returns:

: wholememory_error_code_t

int fork_get_device_count()#

Fork a new process and get device count. Should be called before other CUDA call

Returns:

: CUDA device count, -1 on error

wholememory_error_code_t wholememory_load_from_file(
wholememory_handle_t wholememory_handle,
size_t memory_offset,
size_t memory_entry_size,
size_t file_entry_size,
const char **file_names,
int file_count,
int round_robin_size
)#

Load WholeMemory from binary files, all rank should be called together

Parameters:

  • wholememory_handle – : WholeMemory Handle

  • memory_offset – : load to memory offset

  • memory_entry_size – : entry size of WholeMemory

  • file_entry_size – : entry size in file, should be less than or equal to memory_entry_size

  • file_names – : file names, all binary files will be logically concatenated and loaded.

  • file_count – : number of files.

  • round_robin_size – : continuous embedding number for a rank under round-robin shard mode

Returns:

: wholememory_error_code_t

wholememory_error_code_t wholememory_store_to_file(
wholememory_handle_t wholememory_handle,
size_t memory_offset,
size_t memory_entry_stride,
size_t file_entry_size,
const char *local_file_name
)#

Store local WholeMemory to file, this should be called by all ranks, with different local_file_name.

Parameters:

  • wholememory_handle – : WholeMemory Handle

  • memory_offset – : memory offset to store

  • memory_entry_stride – : entry size of WholeMemory

  • file_entry_size – : entry size in file, should be less than or equal to memory_entry_size

  • local_file_name – : local file to store to

Returns:

: wholememory_error_code_t

bool wholememory_is_intranode_communicator(wholememory_comm_t comm)#
Parameters:

comm – : WholeMemory Comm

Returns:

: bool

bool wholememory_is_intra_mnnvl_communicator(wholememory_comm_t comm)#
bool wholememory_is_build_with_nvshmem()#
struct clique_info_t#
#include <wholememory.h>

Public Members

int is_in_clique#
int clique_first_rank#
int clique_rank#
int clique_rank_num#
int clique_id#
int clique_num#
struct wholememory_unique_id_t#
#include <wholememory.h>

Unique ID for WholeMemory Communicators.

An Opaque handle to WholeMemory Communicators, exposes as char array. Underlying implementation may be ncclUniqueId_t

Public Members

char internal[WHOLEMEMORY_UNIQUE_ID_BYTES]#
On this page