PiP Initialization/Finalization

Functions
int	pip_init (int *pipidp, int *ntasks, void **root_expp, uint32_t opts)
	Initialize the PiP library. More...
int	pip_fin (void)
	Finalize the PiP library. More...

Detailed Description

PiP Initialization/Finalization

Description

PiP initialization/finalization functions

Function Documentation

int pip_init	(	int *	pipidp,
		int *	ntasks,
		void **	root_expp,
		uint32_t	opts
	)

Name

pip_init

Synopsis

#include <pip/pip.h>
int pip_init( int *pipidp, int *ntasks, void **root_expp, uint32_t opts );

Description

This function initializes the PiP library. The PiP root process must call this. A PiP task is not required to call this function unless the PiP task calls any PiP functions.

Description

When this function is called by a PiP root, ntasks, and root_expp are input parameters. If this is called by a PiP task, then those parameters are output returning the same values input by the root.

Description

A PiP task may or may not call this function. If pip_init is not called by a PiP task explicitly, then pip_init is called magically and implicitly even if the PiP task program is NOT linked with the PiP library.

Parameters

[out]	pipidp	When this is called by the PiP root process, then this returns PIP_PIPID_ROOT, otherwise it returns the PiP ID of the calling PiP task.
[in,out]	ntasks	When called by the PiP root, it specifies the maximum number of PiP tasks. When called by a PiP task, then it returns the number specified by the PiP root.
[in,out]	root_expp	If the root PiP is ready to export a memory region to any PiP task(s), then this parameter is to pass the exporting address. If the PiP root is not ready to export or has nothing to export then this variable can be NULL. When called by a PiP task, it returns the exported address by the PiP root, if any.
[in]	opts	Specifying the PiP execution mode and See below.

Execution mode option

Users may explicitly specify the PiP execution mode. This execution mode can be categorized in two; process mode and thread mode. In the process execution mode, each PiP task may have its own file descriptors, signal handlers, and so on, just like a process. Contrastingly, in the pthread executionn mode, file descriptors and signal handlers are shared among PiP root and PiP tasks while maintaining the privatized variables.

To spawn a PiP task in the process mode, the PiP library modifies the clone() flag so that the created PiP task can exhibit the alomost same way with that of normal Linux process. There are three ways implmented; using LD_PRELOAD, modifying GLIBC, and modifying GIOT entry of the clone() systemcall. One of the option flag values; PIP_MODE_PTHREAD, PIP_MODE_PROCESS, PIP_MODE_PROCESS_PRELOAD, PIP_MODE_PROCESS_PIPCLONE, or PIP_MODE_PROCESS_GOT can be specified as the option flag. Or, users may specify the execution mode by the PIP_MODE environment described below.

Returns

Zero is returned if this function succeeds. Otherwise an error number is returned.

Return values

EINVAL	ntasks is negative
EBUSY	PiP root called this function twice or more without calling pip_fin.
EPERM	opts is invalid or unacceptable
EOVERFLOW	ntasks is too large
ELIBSCN	verssion miss-match between PiP root and PiP task

Environment

• PIP_MODE Specifying the PiP execution mmode. Its value can be either thread, pthread, process, process:preload, process:pipclone, or process:got.
• LD_PRELOAD This is required to set appropriately to hold the path to the pip_preload.so file, if the PiP execution mode is PIP_MODE_PROCESS_PRELOAD (the opts in pip_init) and/or the PIP_MODE ennvironment is set to process:preload. See also the pip_mode(1) command to set the environment variable appropriately and easily.
• PIP_STACKSZ Sepcifying the stack size (in bytes). The KMP_STACKSIZE and OMP_STACKSIZE are also effective. The 't', 'g', 'm', 'k' and 'b' posfix character can be used.
• PIP_STOP_ON_START Specifying the PIP ID to stop on start to debug the specified PiP task from the beginning. If the before hook is specified, then the PiP task will be stopped just before calling the before hook.
• PIP_GDB_PATH If thisenvironment is set to the path pointing to the PiP-gdb executable file, then PiP-gdb is automatically attached when an excetion signal (SIGSEGV and SIGHUP by default) is delivered. The signals which triggers the PiP-gdb invokation can be specified the PIP_GDB_SIGNALS environment described below.
• PIP_GDB_COMMAND If this PIP_GDB_COMMAND is set to a filename containing some GDB commands, then those GDB commands will be executed by the GDB in batch mode, instead of backtrace.
• PIP_GDB_SIGNALS Specifying the signal(s) resulting automatic PiP-gdb attach. Signal names (case insensitive) can be concatenated by the '+' or '-' symbol. 'all' is reserved to specify most of the signals. For example, 'ALL-TERM' means all signals excepting SIGTERM, another example, 'PIPE+INT' means SIGPIPE and SIGINT. Some signals such as SIGKILL and SIGCONT cannot be specified.
• PIP_SHOW_MAPS If the value is 'on' and one of the above exection signals is delivered, then the memory map will be shown.
• PIP_SHOW_PIPS If the value is 'on' and one of the above exection signals is delivered, then the process status by using the pips command (see also pips(1)) will be shown.

Bugs

Is is NOT guaranteed that users can spawn tasks up to the number specified by the ntasks argument. There are some limitations come from outside of the PiP library (from GLIBC).

See Also

pip_named_export

pip_export

pip_fin

pip-mode(PiP 1)

pips(PiP 1)

int pip_fin

(

void

)

Name

pip_fin

Synopsis

#include <pip/pip.h>
int pip_fin( void );

Description

This function finalizes the PiP library. After calling this, most of the PiP functions will return the error code EPERM.

Returns

zero is returned if this function succeeds. On error, error number is returned.

Return values

EPERM	pip_init is not yet called
EBUSY	one or more PiP tasks are not yet terminated

Notes

The behavior of calling pip_init after calling this pip_fin is note defined and recommended to do so.

See Also

pip_init