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

Name	Description
name	Name of the data item for subsequent references.
nbytes	Requested size of the data item in bytes.
accessPermissions	Access 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

Error	Description
FAM_ERR_NOPERM	Caller does not have access rights.
FAM_ERR_ALREADYEXIST	Data item name is already present in FAM.
FAM_ERR_NAME_TOO_LONG	Data item name too long.
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.

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
}