openfam::fam::fam_context_open

Returns a user specific fam_context object.

Synopsis

fam_ctx * fam_context_open(void);

Description

This method call returns a user specific fam_ctx object. Non-blocking calls from the context are grouped together for completion, and a fam_quiet invoked from it only enforces completion of all operations invoked from that context. Applications can use both fam_ctx object and fam objects; However, OpenFAM APIs invoked from these objects are tracked separately, and unlike the fam object, context objects only support the data path, atomic and few ordering APIs in OpenFAM.

Input Arguments

None.

Return Values

fam_ctx* returns a user specific fam_ctx object.Throws Fam_Exception on error.

Fam Error Numbers

Notes

An application can invoke data path, atomic and few ordering APIs using the fam_ctx object returned by fam_context_open API.

List of APIs supported by context objects are as follows:

• DataPath Operations
  • fam_put/fam_get (blocking and non-blocking calls).
  • fam_scatter/fam_gather (blocking and non-blocking calls).
  • fam_copy/fam_backup/restore operations.
  
  
• Atomic Operations
  • Fetch based operations like fam_fetch_and, fam_fetch_or, fam_fetch_xor, fam_fetch_add, fam_fetch_subtract, fam_fetch_min, fam_fetch_max, fam_compare_swap, fam_fetch_TYPE where TYPE may be int32_t/uint32_t/int64_t/uint64_t/float/double/int128_t.
  • Non-fetch based operations like fam_set, fam_and, fam_or, fam_xor, fam_add, fam_subtract, fam_min, fam_max, fam_swap
  
  
• Ordering Operations
  • fam_barrier_all
  • fam_fence
  • fam_quiet
  • fam_progress
  • fam_context_open
  • fam_context_close

  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
  		uint64_t *local;
  		uint64_t *local2;
  
  		// look up the descriptor to a previously allocated completion flag
  		Fam_Descriptor *descriptor = myFam->fam_lookup("fam_context", "myRegion");
  		
  		// Create a fam_context to enable separate tracking of completion for non-blocking calls. 
  		fam_context  *myFamCtx = myFam->fam_context_open();	
  		
  		myFamCtx->fam_get_nonblocking(local, descriptor, 6*sizeof(int),10*sizeof(int));
  		myFamCtx->fam_get_nonblocking(local2, descriptor, 26*sizeof(int),10*sizeof(int));
         
  		// The quiet call on myFamCtx only waits for completion of calls from that context, 
  		// but not others made using the myFam object.
  		myFamCtx->fam_quiet();
  		
  		// Close fam_context now to free resources underneath.
  		myFam->fam_context_close(myFamCtx);
  
  		// ... subsequent code here
  	} catch (Fam_Exception &e) {
  		printf("fam API failed: %d: %s\n", e.fam_error(), e.fam_error_msg());
  	}
  		
  	// ... Finalization code follows
  }