openfam::fam::fam_scatter

Copy elements of a data item from local memory to disjoint parts of FAM.

Synopsis

int fam_scatter_blocking(void *local, Fam_Descriptor *descriptor, uint64_t nElements, uint64_t firstElement, uint64_t stride, uint64_t elementSize);

int 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

The non-blocking calls do not return a value on success. The blocking calls return an integer value following normal C convention of 0 for successful completion. At 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 call throws an exception on error.

Exceptions

Exception	Description
Fam_InvalidOption_Exception	incorrect parameters are passed.
Fam_Datapath_Exception	error occurred during write operation over fabric.
FAM_ERR_LIBFABRIC	libfabric error occurred.
Fam_Timeout_Exception	number of libfabric retry count reached the timeout limit. (Only for blocking call)
FAM_ERR_NOPERM	Caller does not have access rights
FAM_ERR_ALREADYEXIST	the data item name is already present in FAM
FAM_ERR_GRPC	there is a communication error with memory server
FAM_ERR_RPC_CLIENT_NOTFOUND	Memory server initialization failure

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
}