openfam::fam::fam_create_region

Create a new region in FAM.

Synopsis

Fam_Region_Descriptor *fam_create_region(char *name, uint64_t size, mode_t permissions, Fam_Region_Attributes* regionAttributes);

Description

This method creates a region in FAM for subsequent use

Input Arguments

Name	Description
name	Name of the region to be created.
size	Requested size of the region in bytes.
permissions	Permissions to be associated with this region.
regionAttributes	Is a structure that holds region attributes such as: redundancyLevel represents the redundancy level for the data items within the region. The supported values for redundancyLevel are: {DEFAULT, NONE, RAID1, RAID5} . The current DEFAULT is NONE. memoryType denotes the type of memory the region is created on. The supported values for memoryType are: {DEFAULT, VOLATILE, PERSISTENT}. PERSISTENT regions will be created in persistent memory, while VOLATILE regions will be created in DRAM. The current DEFAULT is VOLATILE. interleaveEnable denotes if data item interleaving is enabled for the region. The supported values are: {DEFAULT, ENABLE, DISABLE}. A value of DISABLE implies that data items within the region are not interleaved across memory servers, and each data item is hosted within a single memory server (subject to redundancyLevel). A value of ENABLE indicates data item interleaving is enabled, and data items are striped across memory servers using a system-defined interleave block size. The current DEFAULT value is ENABLE. permissionLevel attribute signifies the permission level of the data items allocated in the region. The supported values are: {DEFAULT, REGION, DATAITEM}. A value of REGION implies that the data items allocated within the region inherit the permission from the region. A value of DATAITEM indicates that the data items allocated within the region can have differ ent permission than that of the region. permissionLevel attribute is also tied with the underlying memory registration strategy. If permissionLevel is REGION, the entire region memory is registered for RMA operation during region creation. But, if the value is DATAITEM, individual data item memory is registered at the time of allocation of that data item. The current DEFAULT value is REGION.

Return Values

Descriptor to the created region. Throws Fam_Exception on error.

Fam error numbers

Error	Description
FAM_ERR_NOPERM	Caller does not have access rights.
FAM_ERR_ALREADYEXIST	Region name is already present in FAM.
FAM_ERR_NAME_TOO_LONG	Region name too long.
FAM_ERR_NOT_CREATED	Region creation in FAM failed.
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 the system may round up the actual size of the region to align memory boundaries. Currently the maximum size of a region is limited to 16 EiB by the API. See Design Choices for the current design limits within the OpenFAM reference implementation. Also note that at present maximum region name length supported is 40 characters.

Fam_Region_Descriptor provides a method to retrieve an opaque read-only data structure called Fam_Global_Descriptor which represents the region 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_Region_Descriptor::get_global_descriptor();
Fam_Global_Descriptor gDescriptor = regionDescriptor->get_global_descriptor();

Fam_Region_Descriptor can be instantiated from Fam_Global_Descriptor using the following constructor.

// Fam_Region_Descriptor::Fam_Region_Descriptor(Fam_Global_Descriptor gDescriptor);
Fam_Region_Descriptor *rd = new Fam_Region_Descriptor(gDescriptor);

Example

#include <stdlib.h>
#include <stdio.h>
#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
	
	    Fam_Region_Attributes* regionAttributes = (Fam_Region_Attributes*)calloc(1, sizeof(Fam_Region_Attributes));
	try {
	    	regionAttributes->memoryType = VOLATILE;
		// create a 10 GB region with 0777 permissions for given region attributes
		Fam_Region_Descriptor *rd = myFam->fam_create_region("myRegion", (uint64_t)10000000000, 0777, regionAttributes);
		
		/ use the created region...
		printf("fam_create_region successful\n");
		
		// ... continuation code here
		
		// we are finished. Destroy the region and everything in it
		myFam->fam_destroy_region(rd);
		printf("fam_destroy_region successful\n");
	} catch (Fam_Exception &e) {
		printf("Create/Destroy region failed: %d: %s\n", e.fam_error(), e.fam_error_msg());
	}
	free(regionAttributes);
	// ... finalization code here
	
}