openfam::fam::fam_scatter
Copy elements of a data item from local memory to disjoint parts of FAM.
Synopsis
void fam_scatter_blocking(void *local, Fam_Descriptor *descriptor, uint64_t nElements, uint64_t firstElement, uint64_t stride, uint64_t elementSize);
void fam_scatter_blocking(void *local, Fam_Descriptor *descriptor, uint64_t nElements, uint64_t *elementIndex, uint64_t elementSize);
void fam_scatter_nonblocking(void *local, Fam_Descriptor *descriptor, uint64_t nElements, uint64_t firstElement, uint64_t stride, uint64_t elementSize);
void fam_scatter_nonblocking(void *local, Fam_Descriptor *descriptor, uint64_t nElements, uint64_t *elementIndex, uint64_t elementSize);
Description
Copy elements of a data item from local memory to FAM based on a constant or indexed stride.
Input Arguments
Name | Description |
---|---|
local | Pointer to appropriately sized area of local memory. |
descriptor | Descriptor associated with the data item in FAM. |
nElements | Number of elements to put. |
firstElement | Index (in FAM) of the first element within the data item to put. |
elementIndex | A local array containing element indexes in FAM. |
stride | Stride to use when putting elements. |
elementSize | Size of each element to scatter. |
Return Values
These calls do not return a value on success. Upon return, FAM contains a copy of the
data elements for the blocking calls. Data in FAM is not guaranteed
until successful completion of a subsequent fam_quiet()
call for the
non-blocking calls. Both non-blocking and blocking calls throw
Fam_Exception
on error.
Fam Error Numbers
Error | Description |
---|---|
FAM_ERR_INVALID | API called with incorrect parameters. |
FAM_ERR_NOPERM | Caller does not have access rights. |
FAM_ERR_LIBFABRIC | Libfabric error occurred. |
FAM_ERR_NOTFOUND | Item not found in the region. |
FAM_ERR_RPC | Communication error from grpc layer. |
FAM_ERR_RPC_CLIENT_NOTFOUND | RPC service not available. |
FAM_ERR_METADATA | Metadata service error. |
FAM_ERR_MEMORY | Memory service error. |
FAM_ERR_RESOURCE | Resource not available. |
FAM_ERR_TIMEOUT | Number of libfabric retry count reached. |
Notes
This API assumes that the data item contains uniformly sized elements (e.g, a large array). Currently, the API scatters elements within a single data item. Note that two versions of each API exist: a strided gather/scatter that assumes a constant stride and an indexed gather/scatter that uses an index array to gather/scatter the elements.
Example
#include <string.h> #include <fam/fam.h> #include <fam/fam_exception.h> using namespace std; using namespace openfam; int main(void) { fam *myFam = new fam(); // ... Initialization code here try { // look up the descriptor to a previously allocated data item // (a 50-element integer array) Fam_Descriptor *descriptor = myFam->fam_lookup("myItem", "myRegion"); // local data int local[] = {0,1,2,3,4}; // scatter the data into myItem[1,3,5,7,9] myFam->fam_scatter_blocking(local, descriptor, 5L, (uint64_t) 1, 2, sizeof(int)); // in addition, place them in myItem[10,17,13,15,16] respectively uint64_t indexes[] = {10, 17, 13, 15, 16}; myFam->fam_scatter_blocking(local, descriptor, 5L, indexes, sizeof(int)); // ... we now have the correct elements in FAM printf("fam_scatter successful. Correct elements are now in FAM.\n"); } catch (Fam_Exception &e) { printf("fam API failed: %d: %s\n", e.fam_error(), e.fam_error_msg()); } // ... Finalization code follows }