openfam::fam::fam_initialize

Initialize the OpenFAM library.

Synopsis

void fam_initialize(const char *groupName, Fam_Options *options);

Description

This method is required to be the first method called when a processing element uses the OpenFAM library. It initializes internal data structures within the library that allow the processing element to participate in the application. Normally, called by all PEs at the start of the program.

Input Arguments

Name	Description
groupName	Name that defines an application group. All cooperating PEsmust provide the same group name.
options	Pre-defined options that a processing element provides to the OpenFAM library.

fam_initialize() takes a defined object of type Fam_Options as input

typedef struct {
	char *defaultRegionName;
	char *memoryServer;
	char *grpcPort;
	char *libfabricPort;
	char *libfabricProvider;
	char *famThreadModel;
	char *allocator;
	char *famContextModel;
	char *numConsumer;
	char *runtime;
} Fam_Options;

Name	Description	Default Value
memoryServer	Memory Server(s) to be used by OpenFam APIs. The value is given as MemoryServerId:MemoryServerIPaddress. The MemoryServerId should always be zero in current implementation. The default value is taken as "0:127.0.0.1". i.e, localhost as memory server with memory server id as 0.	"0:127.0.0.1"
grpcPort	Port to be used by OpenFam memory allocator operations.	"8787"
libfabricPort	Port to be used for libfabric operations.	"7500"
libfabricProvider	Libfabric provider to be used by OpenFam libfabric datapath operations. The supported options are "sockets" and "psm2".	"sockets"
allocator	Type of allocator implementation used by OpenFAM API. Supported allocator implementations are: "grpc" – Memory Server implementation that can be used in a standard cluster. "nvmm" – Shared Memory implementation that is usable in large shared memory scale-up machines.	"grpc"
numConsumer	Number of consumer threads for shared memory model – "nvmm" allocator.	"1"
runtime	FAM runtime environment used. Supported values are "pmix", "pmi2", "none".	"pmix"

Application should set the options value to zero to use the default option values.

Fam_Options *fm = (Fam_Options*)malloc(sizeof(Fam_Options));

memset((void *)fm, 0, sizeof(Fam_Options));

Note: The following options are not supported in current implementation and should always be set to zero to use the default values.

defaultRegionName, famThreadModel and famContextModel.

Return Values

None. Throws an exception on error.

Exceptions

Exception	Description
Fam_InvalidOption_Exception	If invalid option values are specified
Fam_Datapath_Exception	libfabric initialization failure
Fam_Allocator_Exception	allocator initialization failure
Fam_Pmi_Exception	runtime initialization failure

Notes

Fields may be specified in options in the future to support parameters or other variables that have traditionally been provided to the runtime via environment variables.

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();
	Fam_Options *fm = (Fam_Options*)malloc(sizeof(Fam_Options));
	memset((void *)fm, 0, sizeof(Fam_Options));
	// Set specific options that are needed by the implementation
	fm->memoryServer = strdup("0:10.0.0.25");
	fm->libfabricProvider = strdup("sockets");
	try {
		myFam->fam_initialize("myApplication", fm);
		printf("FAM initialized\n");
	} catch (Fam_Exception& e) {
		printf("FAM Initialization failed: %s\n", e.fam_error_msg());
		myFam->fam_abort(-1); // abort the program
		// note that fam_abort currently returns after signaling
		// so we must terminate with the same value
		return -1;
	}
	myFam->fam_finalize("myApplication");
	printf("FAM finalized\n");
	return 0;
}