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. If null, the default specified during fam_initialize() is used.

Return Values

Exception	Description
FAM_ERR_NOPERM	Caller does not have access rights
FAM_ERR_ALREADYEXIST	the data item name is already present in FAM
FAM_ERR_GRPC	there is a communication error with memory server
FAM_ERR_RPC_CLIENT_NOTFOUND	Memory server initialization failure

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.

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 are 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("Successully allocated 50 unnamed integer elements\n");

		// free allocated space in FAM
		myFam->fam_deallocate(descriptor);
		printf("Successully 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
}