openfam::fam::fam_get

Copy a segment of memory from FAM to local memory.

Synopsis

int fam_get_blocking(void *local, Fam_Descriptor *descriptor, uint64_t offset, uint64_t nbytes);

void fam_get_nonblocking(void *local, Fam_Descriptor *descriptor, uint64_t offset, uint64_t nbytes);

Description

Copy (part of) some data item from FAM to local memory.

Input Arguments

Return Values

The non-blocking call does not return a value on success. The blocking call returns an integer value following normal C convention of 0 for successful completion. Both non-blocking and blocking call throw an exception on error.

Exceptions

Notes

The local memory pointer must point to an area of memory sufficient to accommodate the incoming data (nbytes). Insufficient allocation of local memory may cause segmentation violations or corrupted data in local memory.

At return, the memory pointed to by local contains a copy of the data in FAM for the blocking call. For the non-blocking call, the memory pointed to by the local pointer is not guaranteed to contain a copy of the data in FAM until after a successful completion of a fam_quiet() call.

Examples

// Example of blocking get
#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");
	
		// allocate local memory to receive 10 elements
		int *local = (int *)malloc(10 * sizeof(int));
	
		// copy elements 6-15 from FAM into elements 0-9 in local memory
		myFam->fam_get_blocking(local, descriptor, 6*sizeof(int), 10*sizeof(int));
	
		// ... we now have a copy in local memory to work with
		printf("fam_get_blocking success. Data now in local memory\n");
	 } catch (Fam_Exception &e) {
		printf("fam API failed: %d: %s\n", e.fam_error(), e.fam_error_msg());
	 }
	 // ... Finalization code
}
	
// Example of non-blocking get
#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 *descriptor1 = myFam->fam_lookup("myItem", "myRegion");

		// allocate local memory to receive 10 elements from different offsets
		// within the data item
		int *local1 = (int *) malloc(10 * sizeof(int));
		int *local2 = (int *) malloc(10 * sizeof(int));
		// copy elements 6-15 from FAM into local1 elements 0-9 in local memory
	
		myFam->fam_get_nonblocking(local1, descriptor1, 6*sizeof(int), 10*sizeof(int));
		// copy elements 26-35 from FAM into local2 elements 0-9 in local memory
	
		myFam->fam_get_nonblocking(local2, descriptor1, 26*sizeof(int), 10*sizeof(int));

		// wait for previously issued non-blocking operations to complete
		myFam->fam_quiet();

		// ... we now have copies in local memory to work with

		printf("fam_get_nonblocking success. All copies of data now in local
		memory\n");
	 } catch (Fam_Exception &e) {
		printf("fam API failed: %d: %s\n", e.fam_error(), e.fam_error_msg());
	 }

	 // ... Finalization code follows
}