openfam::fam::fam_compare_swap

Atomically conditionally replace a value in FAM with the given value and return the old value.

Synopsis

int32_t fam_compare_swap(Fam_Descriptor *descriptor, uint64_t offset, int32_t oldValue, int32_t newValue);

int64_t fam_compare_swap(Fam_Descriptor *descriptor, uint64_t offset, int64_t oldValue, int64_t newValue);

uint32_t fam_compare_swap(Fam_Descriptor *descriptor, uint64_t offset, uint32_t oldValue, uint32_t newValue);

uint64_t fam_compare_swap(Fam_Descriptor *descriptor, uint64_t offset, uint64_t oldValue, uint64_t newValue);

int128_t fam_compare_swap(Fam_Descriptor *descriptor, uint64_t offset, int128_t oldValue, int128_t newValue);

Description

These methods atomically perform a compare and swap of a value in FAM, and return the old value from FAM. All of these methods atomically implement the following algorithm (where TYPE is one of the data types listed in the synopsis):

TYPE cas(TYPE *p, TYPE oldValue, TYPE newValue){
  if(*p != oldValue){
    return *p;
  } else {
    *p = newValue;
    return oldValue;
  }
}

Input Arguments

Name	Description
descriptor	Descriptor associated with the data item.
offset	Offset within the data item in FAM where value is located.
oldValue	Expected old value at the FAM location.
newValue	New value to use if successful.

Return Values

The old value from FAM. Throws an exception on error.

Exceptions

Exception	Description
Fam_InvalidOption_Exception	incorrect parameters are passed.
Fam_Datapath_Exception	error occurred during atomic operation over fabric.
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_GRPC	if there is a communication error with memory server
FAM_ERR_RPC_CLIENT_NOTFOUND	Memory server initialization failure
Fam_Timeout_Exception	number of libfabric retry count reached

Notes

These methods atomically compare a value in FAM with an expected value and if the value in FAM is equal to the expected value, swap a new value. 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. GCC currently does not define int128_t; it is defined in fam.h.

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 compare and replaces the first integer element in FAM with 0
		// only if it contains 100; It returns the old value
		int32_t oldValue = myFam->fam_compare_swap(descriptor, 0, 100, 0);

		// The first integer in FAM is replaced with 0 only if it contains 100;
		// Old value is returned
		printf("Old value of first integer element in FAM: %d\n", oldValue);
		
		// ... subsequent code here
	} catch (Fam_Exception &e) {
		printf("fam API failed: %d: %s\n", e.fam_error(), e.fam_error_msg());
	}
	// ... Finalization code follows
}