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
}