Generic API

an abstraction of communication between parallel tasks More...

Collaboration diagram for Generic API:

Modules
	Collective API
	I/O operations that involve all tasks that have opened a file.

Typedefs
typedef int(*	sion_create_lcg_cb) (void **local_commgroup, void *global_commgroup, int grank, int gsize, int lrank, int lsize, int filenumber, int numfiles)
	creates data structures for local communication group More...
typedef int(*	sion_free_lcg_cb) (void *local_commgroup)
	free data structure which local_commgroup points on
typedef int(*	sion_barrier_cb) (void *commgroup)
	performs a barrier on all tasks described with commgroup (local or global) More...
typedef int(*	sion_bcastr_cb) (void *data, void *commgroup, int datatype, int nelem, int root)
	performs a broadcast operation from task root to all other tasks described with commgroup (local or global) More...
typedef int(*	sion_gatherr_cb) (void *indata, void *outdata, void *commgroup, int datatype, int nelem, int root)
	performs a gather operation on all tasks described with commgroup (local or global) More...
typedef int(*	sion_gathervr_cb) (void *indata, void *outdata, void *commdata, int datatype, int *count, int nelem, int root)
	performs a gather operation on all tasks described with commdata (local or global) More...
typedef int(*	sion_scatterr_cb) (void *indata, void *outdata, void *commgroup, int datatype, int nelem, int root)
	performs a scatter operation on all tasks described with commgroup (local or global) More...
typedef int(*	sion_scattervr_cb) (void *indata, void *outdata, void *commgroup, int datatype, int *count, int nelem, int root)
	performs a scatter operation on all tasks described with commgroup (local or global) More...
typedef char *(*	sion_get_multi_filename_cb) (const char *, int)
typedef int64_t(*	sion_gather_execute_cb) (const void *, int64_t, void *, int, int, int, int, int64_t process_cb(const void *, int64_t *, int), void *, bool spec_iterator_cb(void *, int64_t *))
typedef int64_t(*	sion_execute_scatter_cb) (void *, int64_t, void *, int, int, int, int, int64_t process_cb(void *, int64_t *, int), void *, bool spec_iterator_cb(void *, int64_t *))
typedef int(*	sion_get_capability_cb) (void *)
typedef struct sion_generic_options	sion_generic_options
	Holds non-essential arguments for sion_generic_paropen(). More...

Functions
int	sion_generic_create_api (char *name)
	Create new api. More...
int	sion_generic_free_api (int aip)
	free new api More...
int	sion_generic_register_create_local_commgroup_cb (int aid, sion_create_lcg_cb cb)
	register callback to create local communication group
int	sion_generic_register_free_local_commgroup_cb (int aid, sion_free_lcg_cb cb)
	register callback to free local communication group
int	sion_generic_register_barrier_cb (int aid, sion_barrier_cb cb)
	register callback for communication
int	sion_generic_register_bcastr_cb (int aid, sion_bcastr_cb cb)
	register callback for communication
int	sion_generic_register_gatherr_cb (int aid, sion_gatherr_cb cb)
	register callback for communication
int	sion_generic_register_gathervr_cb (int aid, sion_gathervr_cb cb)
	register callback for communication
int	sion_generic_register_scatterr_cb (int aid, sion_scatterr_cb cb)
	register callback for communication
int	sion_generic_register_scattervr_cb (int aid, sion_scattervr_cb cb)
	register callback for communication
int	sion_generic_register_get_multi_filename_cb (int aid, sion_get_multi_filename_cb cb)
int	sion_generic_register_gather_and_execute_cb (int aid, sion_gather_execute_cb cb)
	register callback for communication
int	sion_generic_register_execute_and_scatter_cb (int aid, sion_execute_scatter_cb cb)
	register callback for communication
int	sion_generic_register_get_capability_cb (int aid, sion_get_capability_cb cb)
int	sion_generic_paropen (int aid, const char *filename, sion_open_mode mode, void *gcommgroup, int grank, int gsize, int filenumber, int numfiles, int lrank, int lsize, const sion_generic_options *options)
	Open a SIONlib file through a generic interface. More...
int	sion_generic_parclose (int sid)
	Close a SIONlib file. More...
int	sion_generic_paropen_mapped (int aid, char *fname, const char *file_mode, int *numFiles, void *gcommgroup, int grank, int gsize, int *nlocaltasks, int **globalranks, int64_t **chunksizes, int **mapping_filenrs, int **mapping_lranks, int32_t *fsblksize, FILE **fileptr)
int	sion_generic_parclose_mapped (int sid)
int	sion_generic_parreinit (int sid, int64_t chunksize)
sion_generic_options *	sion_generic_options_new ()
	Allocates and initializes an instance of sion_generic_options More...
void	sion_generic_options_delete (sion_generic_options *options)
	Delete an instance of sion_generic_options More...
void	sion_generic_options_set_chunksize (sion_generic_options *options, int64_t chunksize)
	Set the chunk size of a logical file in the container. More...
void	sion_generic_options_set_fsblksize (sion_generic_options *options, int32_t fsblksize)
	Set the file system block size to assume. More...
void	sion_generic_options_set_keyval_mode (sion_generic_options *options, sion_keyval_mode keyval_mode)
	Set the key-value mode to use for a container. More...
void	sion_generic_options_set_buddy (sion_generic_options *options)
	Enable buddy checkpointing mechanism. More...
void	sion_generic_options_set_buddylevel (sion_generic_options *options, int32_t buddylevel)
	Enable buddy checkpointing mechanism. More...
void	sion_generic_options_set_collective (sion_generic_options *options)
	Enable collective I/O. More...
void	sion_generic_options_set_collective_size (sion_generic_options *options, int32_t size)
	Enable collective I/O. More...
void	sion_generic_options_set_collective_merge (sion_generic_options *options)
	Use collective merging. More...
void	sion_generic_options_set_lowlevel_api (sion_generic_options *options, sion_lowlevel_api lowlevel_api)
	Set the low-level API to use for opening a container. More...
void	sion_generic_options_set_endianness (sion_generic_options *options, sion_endianness endianness)
	Set the endianness for the contents of a container. More...

Detailed Description

an abstraction of communication between parallel tasks

Introduction

The generic API of SIONlib is designed to implement a user-defined SIONlib parallel API. This new feature of SIONlib enables also SIONlib for those application, not using one of the SIONlib standard communication layers like MPI, OpenMP, or hybrid (MPI+OpenMP).

SIONlib requires only a few communication functions to collect and distributed meta-data information during open- and close-call among the parallel tasks. Most of these communication functions are collective operation like bcast, gather, or scatter.

Communications Groups

According to the existing SIONlib standard communication layer, SIONlib uses two different groups of tasks:

• Global
  • This communication group includes all tasks which will be part of the SIONlib file operation (e.g. MPI_COMM_WORLD).
• Local
  • SIONlib uses this communination group to collect those tasks which accesse the same physical file.

A data structure has to be defined and allocated for the global commgroup before calling sion_generic_paropen() and a pointer to the data structure has to be passed to sion_generic_paropen() as a parameter.

The local commgroup has to be created when opening a file. Therefore, a callback function for creating and freeing such a commgroup has to be registered. The callback functions for communication will get a pointer to one of these commgroup data structures afterwards as a parameter.

SIONlib uses both commgroups for communication: the global commgroup for example to collect and distribute task-to-file mapping information. The local commgroup will be used to collect and distribute file meta information (e.g. chunksizes). Callback functions are therefore required to be able to perform the implemented communication operation on both commgroup.

The second, local communication group will be defined by SIONlib according to the parameters filenumber, numfiles, lrank and lsize given by each task to sion_generic_paropen(). For the definition of the commgroup SIONlib also uses a callback function internally, which has to create the commgroup and store the data into the corresponding data structure.

Remarks:

• The communination groups are not dynamic. This means, the communication groups must not be changed after a file is opened.

Usage

For using the generic SIONlib API the following steps are required:

Definition phase

• Definition of callback functions and commgroups
• Registration of callback functions and commgroups

I/O-operation phase

• Parallel open of SIONlib file
• I/O-operations (read/write, ..)
• Parallel close of SIONlib file

Example

An example can be found in the parallel test section of the SIONlib distribution:

• <topdir>/test/serial/test_genapi_1.c (generic API, only create and link test)
• <topdir>/test/parallel/test_genapi_1.c (generic API)
• <topdir>/test/parallel/test_genapi_2.c (generic mapped API)

The example defines a SIONlib generic API and performs some I/O tests with the new API. Internally the API uses MPI to implement the communication operations.

Typedef Documentation

sion_barrier_cb

typedef int(* sion_barrier_cb) (void *commgroup)

performs a barrier on all tasks described with commgroup (local or global)

Blocks until all processes have reached this routine.

Definition at line 146 of file sion_generic.h.

sion_bcastr_cb

typedef int(* sion_bcastr_cb) (void *data, void *commgroup, int datatype, int nelem, int root)

performs a broadcast operation from task root to all other tasks described with commgroup (local or global)

Replicates data on root at memory position data of size nelem to memory position data of all other tasks.

Definition at line 151 of file sion_generic.h.

sion_create_lcg_cb

typedef int(* sion_create_lcg_cb) (void **local_commgroup, void *global_commgroup, int grank, int gsize, int lrank, int lsize, int filenumber, int numfiles)

creates data structures for local communication group

• only local_commgroup is output parameter: pointer to new data structure
• will be called as soon as all information is available (e.g. after read of mapping during paropen)

Definition at line 137 of file sion_generic.h.

sion_gatherr_cb

typedef int(* sion_gatherr_cb) (void *indata, void *outdata, void *commgroup, int datatype, int nelem, int root)

performs a gather operation on all tasks described with commgroup (local or global)

• collects nelem of data type datatype from each task from memory at indata and stores data of tasks on task root in memory at position outdata
• nelem has same the value on each task, outdata is the of size nelem * ntasks
• on root indata and outdata are not overlapping

Definition at line 159 of file sion_generic.h.

sion_gathervr_cb

typedef int(* sion_gathervr_cb) (void *indata, void *outdata, void *commdata, int datatype, int *count, int nelem, int root)

performs a gather operation on all tasks described with commdata (local or global)

• collects nelem of data type datatype from each tasks from memory at indata and stores data of tasks on task root in memory at position outdata
• nelem can be different among tasks (or zero), size of outdata is sum of nelem on each task
• count is an array containing the number of elems per task, this array will only to be provided on root, otherwise NULL
• on root indata and outdata are not overlapping

Definition at line 168 of file sion_generic.h.

sion_generic_options

typedef struct sion_generic_options sion_generic_options

Holds non-essential arguments for sion_generic_paropen().

These are:

• the sizes of chunks for the logical file opened by this task,
• the size of a file system block to assume,
• whether and in what mode to use SIONlib's key-value mechanism,
• whether to use the buddy redundancy mechanism,
• whether to use collective I/O,
• what low-level API to use for file system access,
• the endianness of user data in the file.

Definition at line 253 of file sion_generic.h.

sion_scatterr_cb

typedef int(* sion_scatterr_cb) (void *indata, void *outdata, void *commgroup, int datatype, int nelem, int root)

performs a scatter operation on all tasks described with commgroup (local or global)

• distributes nelem of data type datatype to each tasks from memory at outdata + offset on task root and stores data in memory at position indata
• nelem has same value on each task, outdata is of size nelem * ntasks
• on root indata and outdata are not overlapping

Definition at line 176 of file sion_generic.h.

sion_scattervr_cb

typedef int(* sion_scattervr_cb) (void *indata, void *outdata, void *commgroup, int datatype, int *count, int nelem, int root)

performs a scatter operation on all tasks described with commgroup (local or global)

• distributes nelem of data type datatype to each tasks from memory at outdata + offset on task root and stores data in memory at position indata
• count is an array containing the number of elems per task, this array must only be provided on root, otherwise NULL
• nelem can be different among tasks (or zero), size of outdata is sum of nelem on each task
• on root indata and outdata are not overlapping

Definition at line 185 of file sion_generic.h.

Function Documentation

sion_generic_create_api()

int sion_generic_create_api

(

char *

name

)

Create new api.

Parameters

name	a name for that API which will be used in debugging messages for example

Returns

an integer value containing an API descriptor

Definition at line 31 of file sion_generic.c.

sion_generic_free_api()

int sion_generic_free_api

(

int

aip

)

free new api

Frees internal data structures for this API.

Definition at line 59 of file sion_generic.c.

sion_generic_options_delete()

void sion_generic_options_delete

(

sion_generic_options *

options

)

Delete an instance of sion_generic_options

Parameters

[in]

options

a pointer to the instance to delete

Definition at line 669 of file sion_generic.c.

sion_generic_options_new()

sion_generic_options* sion_generic_options_new

(

)

Allocates and initializes an instance of sion_generic_options

Returns

a pointer to the new instance or NULL if allocation failed

Definition at line 660 of file sion_generic.c.

sion_generic_options_set_buddy()

void sion_generic_options_set_buddy

(

sion_generic_options *

options

)

Enable buddy checkpointing mechanism.

Has the same effect as sion_generic_options_set_buddylevel(options, 1).

See also

resiliency

Parameters

[in]

options

an options object

Definition at line 689 of file sion_generic.c.

References sion_generic_options_set_buddylevel().

sion_generic_options_set_buddylevel()

void sion_generic_options_set_buddylevel	(	sion_generic_options *	options,
		int32_t	buddylevel
	)

Enable buddy checkpointing mechanism.

Enables a specific level of buddy redundancy.

See also

resiliency

Parameters

[in]	options	an options object
[in]	buddylevel	the level of redundancy to use

Definition at line 694 of file sion_generic.c.

Referenced by sion_generic_options_set_buddy(), sion_mpi_options_set_buddylevel(), and sion_ompi_options_set_buddylevel().

Here is the caller graph for this function:

sion_generic_options_set_chunksize()

void sion_generic_options_set_chunksize	(	sion_generic_options *	options,
		int64_t	chunksize
	)

Set the chunk size of a logical file in the container.

Parameters

[in,out]	options	an options object
[in]	chunksize	chunk sizes for the logical file opened by this process

Definition at line 674 of file sion_generic.c.

Referenced by sion_mpi_options_set_chunksize(), sion_omp_options_set_chunksize(), and sion_ompi_options_set_chunksize().

Here is the caller graph for this function:

sion_generic_options_set_collective()

void sion_generic_options_set_collective

(

sion_generic_options *

options

)

Enable collective I/O.

The size of collector groups will be determined via heuristics.

See also

Collective API

Parameters

[in]

options

an options object

Definition at line 699 of file sion_generic.c.

sion_generic_options_set_collective_merge()

void sion_generic_options_set_collective_merge

(

sion_generic_options *

options

)

Use collective merging.

See also

Collective API

Parameters

[in]

options

an options object

Definition at line 709 of file sion_generic.c.

Referenced by sion_mpi_options_set_collective_merge(), sion_omp_options_set_collective_merge(), and sion_ompi_options_set_collective_merge().

Here is the caller graph for this function:

sion_generic_options_set_collective_size()

void sion_generic_options_set_collective_size	(	sion_generic_options *	options,
		int32_t	size
	)

Enable collective I/O.

See also

Collective API

Parameters

[in]	options	an options object
[in]	size	size of the collector groups

Definition at line 704 of file sion_generic.c.

Referenced by sion_mpi_options_set_collective_size(), sion_omp_options_set_collective_size(), and sion_ompi_options_set_collective_size().

Here is the caller graph for this function:

sion_generic_options_set_endianness()

void sion_generic_options_set_endianness	(	sion_generic_options *	options,
		sion_endianness	endianness
	)

Set the endianness for the contents of a container.

Parameters

[in,out]	options	an options object
[in]	endianness	the endianness of the contents

Definition at line 722 of file sion_generic.c.

Referenced by sion_mpi_options_set_endianness(), sion_omp_options_set_endianness(), and sion_ompi_options_set_endianness().

Here is the caller graph for this function:

sion_generic_options_set_fsblksize()

void sion_generic_options_set_fsblksize	(	sion_generic_options *	options,
		int32_t	fsblksize
	)

Set the file system block size to assume.

Parameters

[in,out]	options	an options object
[in]	fsblksize	the file system block size

Definition at line 679 of file sion_generic.c.

Referenced by sion_mpi_options_set_fsblksize(), sion_omp_options_set_fsblksize(), and sion_ompi_options_set_fsblksize().

Here is the caller graph for this function:

sion_generic_options_set_keyval_mode()

void sion_generic_options_set_keyval_mode	(	sion_generic_options *	options,
		sion_keyval_mode	keyval_mode
	)

Set the key-value mode to use for a container.

Parameters

[in,out]	options	an options object
[in]	keyval_mode	the key-value mode to use

Definition at line 684 of file sion_generic.c.

Referenced by sion_mpi_options_set_keyval_mode(), sion_omp_options_set_keyval_mode(), and sion_ompi_options_set_keyval_mode().

Here is the caller graph for this function:

sion_generic_options_set_lowlevel_api()

void sion_generic_options_set_lowlevel_api	(	sion_generic_options *	options,
		sion_lowlevel_api	lowlevel_api
	)

Set the low-level API to use for opening a container.

Parameters

[in,out]	options	an options object
[in]	lowlevel_api	the low-level API to use

Definition at line 717 of file sion_generic.c.

Referenced by sion_mpi_options_set_lowlevel_api(), sion_omp_options_set_lowlevel_api(), and sion_ompi_options_set_lowlevel_api().

Here is the caller graph for this function:

sion_generic_parclose()

int sion_generic_parclose

(

int

sid

)

Close a SIONlib file.

This function closes the SIONlib file in parallel on all tasks involved in opening it. Therefore the local communication structure, defined at sion_generic_paropen(), will be used internally to collect all the meta data from each task and to write it to the SIONlib file on task zero of the local communication structure. This function has to be called collectively on all tasks of the global communication structure given at opening time.

There is currently no fault tolerance in the meta-data handling. The size of logical files in the container (see SIONlib file format) is held in memory on each task and is not written to disk before calling this function. This means, that the file cannot be read again if it was not closed correctly, e.g. because the disk space limit was reached before. This is a trade-off for the possibility so avoid any kind of communication between the open and the close calls.

Parameters

[in]

sid

SIONlib file handle

Returns

SION_SUCCESS if close is ok

Definition at line 362 of file sion_generic.c.

sion_generic_paropen()

int sion_generic_paropen	(	int	aid,
		const char *	filename,
		sion_open_mode	mode,
		void *	gcommgroup,
		int	grank,
		int	gsize,
		int	filenumber,
		int	numfiles,
		int	lrank,
		int	lsize,
		const sion_generic_options *	options
	)

Open a SIONlib file through a generic interface.

This function opens a SIONlib file for writing or reading data. The chunk sizes are communicated among tasks which enables each task to calculate the correct offset to prevent other tasks from trying to access the same parts of the file. Hence this call is collective and needs to be called by all processes at the same time. With this information globally available following calls of sion_write() and sion_read() do not need any communication.

In write-mode SIONlib will create one or more physical files on disk containing data of all tasks (see also SIONlib file format). The number has to be defined by the parameter numfiles. If numfiles is greater than zero the tasks in gcommgroup will be split into numfiles groups.

On each task the function opens one of the physical files with the POSIX or ANSI C open command mode and sets the file pointer to a task-specific position.

Parameters

[in]	aid	communication API (created via sion_generic_api_create()
[in]	filename	name of file, should be equal on all tasks
[in]	mode	what mode to open the file in
[in,out]	gcommgroup	global communication structure (contains all tasks involved)
[in]	grank	rank of task in gcommgroup
[in]	gsize	number of tasks in gcommgroup
[in]	filenumber	which file out of the numfiles physical files to open (0..numfiles - 1) (only used when creating a container)
[in]	numfiles	number of files to use (only used when creating a container)
[in]	lrank	rank of the task in the per-physical-file communication structure (only used when creating a container)
[in]	lsize	number of tasks in the per-physical-file communication structure (only used when creating a container)
[in]	options	additional options or NULL

Returns

SIONlib file handle or -1 if error occured

Definition at line 727 of file sion_generic.c.

sion_generic_paropen_mapped()

int sion_generic_paropen_mapped	(	int	aid,
		char *	fname,
		const char *	file_mode,
		int *	numFiles,
		void *	gcommgroup,
		int	grank,
		int	gsize,
		int *	nlocaltasks,
		int **	globalranks,
		int64_t **	chunksizes,
		int **	mapping_filenrs,
		int **	mapping_lranks,
		int32_t *	fsblksize,
		FILE **	fileptr
	)

each task specifies a set of globalranks which should opened on this task

Parameters

aid	SIONlib API id
fname	name of file
file_mode	like the type parameter of fopen
numFiles	number of files to use
gcommgroup	global communicator
grank	global rank of calling task
gsize	size of global communicator
nlocaltasks	gives the number of globalranks to be opened by this task
globalranks	an array containing these globalranks to be opened
chunksizes	an array containing the chunksize for each globalrank which is locally opened
mapping_filenrs	an array containing the filenumber for each globalrank which is locally opened
mapping_lranks	an array containing the local rank in the file for each globalrank which is locally opened
fsblksize	file system block size
fileptr	file pointer

Returns

a SIONlib file handle or -1 if an error occurred

• WRITE-Mode
  • The parameters gcommgroup, grank, gsize, numFiles, nlocaltasks, globalranks, chunksizes, mapping_filenrs, mapping_lranks, fsblksize are input parameters. However these have to be defined as variables and initialized before call.
• READ-Mode
  • The parameters gcommgroup, grank, gsize, numfiles, nlocaltasks, globalranks are input parameter.

Definition at line 404 of file sion_generic.c.