openfam::fam::fam_fetch_min

Atomically replaces a value in FAM with the smaller of the value in FAM and a given value, and returns the old value.

Synopsis

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

Description

These methods atomically replace a value in FAM with the smaller of the value in FAM and the given value, and return the old value.

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 compared the existing value at the given location.

Return Values

The original value from FAM. Throws Fam_Exception on error.

Fam Error Numbers

Error	Description
FAM_ERR_INVALID	API called with incorrect parameters.
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_RPC	Communication error from grpc layer.
FAM_ERR_RPC_CLIENT_NOTFOUND	RPC service not available.
FAM_ERR_METADATA	Metadata service error.
FAM_ERR_MEMORY	Memory service error.
FAM_ERR_RESOURCE	Resource not available.
FAM_ERR_TIMEOUT	Number of libfabric retry count reached.

Notes

These methods atomically replace a value in FAM with the minimum of that value and a given 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.

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 replace the first element of the array with the smaller of the current
		// value and 10, and return the old value
		uint32_t oldValue = myFam->fam_fetch_min(descriptor, 0, 10);

		// The first integer in FAM is the smaller of 10 and the previous value, 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
}