openfam::fam::fam_gather

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

Synopsis

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

void 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

These calls do not return a value on success. 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 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

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
}