openfam::fam::fam_gather

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

Synopsis

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

int fam_gather_blocking(void *local, Fam_Descriptor *descriptor, uint64_t nElements, uint64_t *elementIndex, uint64_t elementSize);

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

void fam_gather_nonblocking(void *local, Fam_Descriptor *descriptor, uint64_t nElements, uint64_t *elementIndex, uint64_t elementSize);

Description

Copy elements of a data item from FAM to local memory 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 get.
firstElement	Index (in FAM) of the first element within the data item to get.
elementIndex	An array containing element indexes.
Stride	Stride to use when getting elements.
elementSize	Size of each element to gather.

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, the memory pointed to by local contains a copy of the data elements from FAM for the blocking calls. For non-blocking calls, local memory is not guaranteed to contain data until successful completion of a subsequent fam_quiet() call. 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

The local memory pointer must point to an area of memory sufficient to accommodate the incoming data. Insufficient allocation of local memory may cause segmentation violations or corrupted data in local memory. This API assumes that the data item contains uniformly sized elements (e.g, a large array). Currently, the API gathers elements from within a single data item.

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 {
		Fam_Descriptor *descriptor = myFam->fam_lookup("myItem", "myRegion");
	
		// allocate a 25-element integer array in local memory
		int *local = (int *) malloc(25 * sizeof(int));
	
		// gather all odd elements from myItem into local memory
		// first element is myItem[1]; collect 25 elements with stride 2
		myFam->fam_gather_blocking(local, descriptor, 25, (uint64_t) 1, 2, sizeof(int));
	
		// gather myItem[1,7,13,15,16]
		int *indexedLocal = (int *) malloc(5 * sizeof(int));
		uint64_t indexes[] = {1, 7, 13, 15, 16};
		myFam->fam_gather_blocking(indexedLocal, descriptor, 5, indexes, sizeof(int));
	
		// ... we now have the correct elements in local memory
	 } catch (Fam_Exception &e) {
		printf("fam API failed: %d: %s\n", e.fam_error(), e.fam_error_msg());
	 }
	 // ... Finalization code follows
}