OpenFAM Reference Implementation

openfam::fam::fam_add

Atomically add a value to a data item in FAM.

Synopsis

void fam_add(Fam_Descriptor *descriptor, uint64_t offset, int32_t value);

void fam_add(Fam_Descriptor *descriptor, uint64_t offset, int64_t value);

void fam_add(Fam_Descriptor *descriptor, uint64_t offset, uint32_t value);

void fam_add(Fam_Descriptor *descriptor, uint64_t offset, uint64_t value);

void fam_add(Fam_Descriptor *descriptor, uint64_t offset, float value);

void fam_add(Fam_Descriptor *descriptor, uint64_t offset, double value);

Description

These methods atomically add a value to an existing value in FAM.

Input Arguments

Name Description
descriptor Descriptor associated with the data item.
offset Offset within the data item in FAM where value is located.
value Value to be added to the existing value at the given location.

Return Values

None. Throws Fam_Exception on error.

FAM Error Numbers

ErrorDescription
FAM_ERR_INVALIDAPI called with incorrect parameters.
FAM_ERR_NOPERMCaller does not have access rights.
FAM_ERR_LIBFABRICLibfabric error occurred.
FAM_ERR_NOTFOUNDItem not found in the region.
FAM_ERR_RPC_CLIENT_NOTFOUNDRPC service not available.
FAM_ERR_METADATAMetadata service error.
FAM_ERR_MEMORYMemory service error.
FAM_ERR_RESOURCEResource not available.

Notes

These methods atomically add a value to an existing value in FAM, and return before the operation is complete. Note that the offset argument must point to the correct value for the data type. Availability of these methods is dependent on hardware support for the operations.

Successful completion of a subsequent fam_quiet() call ensures the completion of this atomic operation.

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
		// (an integer array with at least 10 elements)
		Fam_Descriptor *descriptor = myFam->fam_lookup("myItem", "myRegion");
	
		//Atomically add a value of 100 to first integer element in the array
		myFam->fam_add(descriptor, 0, 100);
	
		// ensure that the add operation is complete
		myFam->fam_quiet();
	
		// The first integer in FAM is now added a value of 100
	 } catch (Fam_Exception &e) {
		printf("fam API failed: %d: %s\n", e.fam_error(), e.fam_error_msg());
	 }

	 // ... Finalization code follows
}