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_Redundancy_Level redundancyLevel, ...);

Description

This method creates a region in FAM for subsequent use

Input Arguments

Return Values

Descriptor to the created region. Throws Fam_Exception on error.

Fam error numbers

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
	
	try {
		// create a 10 GB region with 0777 permissions and RAID5 redundancy
		Fam_Region_Descriptor *rd = myFam->fam_create_region("myRegion", (uint64_t)10000000000, 0777, RAID5);
		
		/ 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());
	}
	
	// ... finalization code here
	
}