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 PEs must 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 *cisServer;
	char *grpcPort;
	char *libfabricProvider;
	char *famThreadModel;
	char *cisInterfaceType;
	char *openFamModel;
	char *famContextModel;
	char *numConsumer;
	char *runtime;
	char *fam_default_memory_type;
	char *if_device;
} Fam_Options;

Two additional fields have been added in Fam_Options to achieve better performance with Slingshot interconnect. 

More details can be found here.

Name	Description	Default Value
defaultRegionName	Default region name. Currently ignored by the implementation.	"default"
cisServer	Client Interface Server to be used by OpenFam APIs. The value is given as cisServer IPaddress string.	"127.0.0.1"
grpcPort	Port to be used by OpenFam client interface service operations.	"8787"
libfabricProvider	Libfabric provider to be used by OpenFam libfabric data path operations. The supported options are "sockets", "verbs;ofi_rxm" and "psm2".	"sockets"
famThreadModel	Threading model used. Options are:. "FAM_THREAD_SERIALIZE" - With this option, the application can be multi-threaded. However concurrent invocation of OpenFAM APIs invocation from multiple threads is not allowed. "FAM_THREAD_MULTIPLE" - With this option, the application can be multi-threaded and any threads may invoke OpenFAM APIs.	"FAM_THREAD_SERIALIZE"
cisInterfaceType	Communication interface type to be used between processing element and Client interface service. Supported types are "rpc" and "direct".	"rpc"
openFamModel	Type of OpenFAM memory allocator model implementation used by OpenFAM API. Supported allocator implementations are: "memory_server" – Memory Server implementation that can be used in a standard cluster. "shared_memory" – Shared Memory implementation that is usable in large shared memory scale-up machines.	"memory_server"
famContextModel	Context model used. Currently ignored by the implementation.	"FAM_CONTEXT_DEFAULT"
numConsumer	Number of consumer threads for shared memory model using the nvmm allocator.	"1"
runtime	FAM runtime environment used. Supported values are "PMIX", "PMI2", "NONE".	"PMIX"
fam_default_memory_type	Memory Type to be used for FAM region creation. Supported values are "PERSISTENT", "VOLATILE".	"VOLATILE"
if_device	Interface device used by the PE for communication. Supported values are "ib0", "ib1", etc for verbs, "cxi0". "cxi1" for cxi device.	"ib0" for infiniband, "cxi0" for cxi device.

The 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));

Return Values

None. Throws Fam_Exception on error.

Fam Error Numbers

Error	Description
FAM_ERR_INVALID	API called with incorrect parameters.
FAM_ERR_LIBFABRIC	Libfabric error occurred.
FAM_ERR_RPC	Communication error from grpc layer.
FAM_ERR_RPC_CLIENT_NOTFOUND	RPC service not available.
FAM_ERR_MEMSERV_LIST_EMPTY	Memory service not initialized.

Notes

Additional 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.

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

defaultRegionName and famContextModel

Alternatively, the application can pass these options using configuration files. See Configuration Files for details. However, fam_initialize() routine will give precedence to the options passed as Fam_Options argument over the options present in configuration files.

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->cisServer = strdup("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;
}