OpenFAM Reference Implementation

openfam::fam::fam_allocate

Allocate a data item in a region of FAM.

Synopsis

Fam_Descriptor *fam_allocate(char *name, uint64_t nbytes, mode_t accessPermissions, Fam_Region_Descriptor *region);
Fam_Descriptor *fam_allocate(uint64_t nbytes, mode_t accessPermissions, Fam_Region_Descriptor *region);

Description

These methods allocate space for a data item in some region of FAM.

Input Arguments

NameDescription
nameName of the data item for subsequent references.
nbytesRequested size of the data item in bytes.
accessPermissionsAccess permissions for this data item.
region Descriptor for the region where the data item is being created.

 

Return Values

Descriptor to the allocated data item. Throws Fam_Exception on error.

Fam Error numbers

ErrorDescription
FAM_ERR_NOPERMCaller does not have access rights.
FAM_ERR_ALREADYEXISTData item name is already present in FAM.
FAM_ERR_NAME_TOO_LONGData item name too long.
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.

Notes

Note that these methods may allocate space greater than the requested size to maintain an implementation dependent byte alignment. The allocated space is zeroed out during allocation. If a name is provided during allocation, it can be used within subsequent calls to fam_lookup() to retrieve the associated descriptor. If a name is not provided during allocation, then the program itself is responsible for saving and tracking the descriptor if required later, since the data in FAM will be unreachable without the descriptor. Also note that at present maximum data item name length supported is 40 characters.

Fam_Descriptor provides a method to retrieve an opaque read-only data structure called Fam_Global_Descriptor which represents both the region and data item in FAM. Fam_Global_Descriptor can be freely copied, and shared across processing nodes by the program, and is portable across operating system and program instances.

// Fam_Global_Descriptor Fam_Descriptor::get_global_descriptor();
Fam_Global_Descriptor gDescriptor = famDescriptor->get_global_descriptor();

Fam_Descriptor can be instantiated from Fam_Global_Descriptor using the following constructor.

// Fam_Descriptor::Fam_Descriptor(Fam_Global_Descriptor gDescriptor);
Fam_Descriptor *dataItem = new Fam_Descriptor(gDescriptor);

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 {
		Fam_Region_Descriptor *region = myFam->fam_lookup_region("myRegion");
		// create 50 element unnamed integer array in FAM with 0600
		// (read/write by owner) permissions in myRegion
		Fam_Descriptor *descriptor = myFam->fam_allocate((uint64_t)(50 * sizeof(int)), 0600, region);

		printf("Successfully allocated 50 unnamed integer elements\n");

		// free allocated space in FAM
		myFam->fam_deallocate(descriptor);
		printf("Successfully de-allocated 50 unnamed integer elements\n");
	} catch (Fam_Exception &e) {
		printf("fam API failed: %d: %s\n", e.fam_error(), e.fam_error_msg());
	 }
	 // ... Finalization code here
}