OpenFAM Reference Implementation

openfam::fam::fam_fetch_subtract

Atomically subtracts a value from a value in FAM, and returns the old value.

Synopsis

int32_t fam_fetch_subtract(Fam_Descriptor *descriptor, uint64_t offset, int32_t value);
int64_t fam_fetch_subtract(Fam_Descriptor *descriptor, uint64_t offset, int64_t value);
uint32_t fam_fetch_subtract(Fam_Descriptor *descriptor, uint64_t offset, uint32_t value);
uint64_t fam_fetch_subtract(Fam_Descriptor *descriptor, uint64_t offset, uint64_t value);
float fam_fetch_subtract(Fam_Descriptor *descriptor, uint64_t offset, float value);
double fam_fetch_subtract(Fam_Descriptor *descriptor, uint64_t offset, double value);

Description

These methods atomically subtract a value from the value in FAM, and return the old value.

Input Arguments

NameDescription
descriptorDescriptor associated with the data item.
offsetOffset within the data item in FAM where value is located.
valueValue to be subtracted from the existing value at the given location.

Return Values

The original value from FAM. 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_RPCCommunication error from grpc layer.
FAM_ERR_RPC_CLIENT_NOTFOUNDRPC service not available.
FAM_ERR_METADATAMetadata service error.
FAM_ERR_MEMORYMemory service error.
FAM_ERR_RESOURCEResource not available.
FAM_ERR_TIMEOUTNumber of libfabric retry count reached.

Notes

These methods atomically subtract a value from the existing value in FAM. The old value is returned. 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.

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
		Fam_Descriptor *descriptor = myFam->fam_lookup("myItem", "myRegion");
	
		// Atomically subtract 10 from the first integer element in the array
		// and return the old value
		uint32_t oldValue = myFam->fam_fetch_subtract(descriptor, 0, 10);

		// The first integer in FAM has 10 subtracted from it, and the old value is returned
	
		// ... subsequent code here
	} catch (Fam_Exception &e) {
		printf("fam API failed: %d: %s\n", e.fam_error(), e.fam_error_msg());
	}
	
	// ... Finalization code follows
}