Functions
void	pip_spawn_from_main (pip_spawn_program_t progp, char prog, char argv, char envv, void exp, void aux)
	Setting information to invoke a PiP task starting from the main function. More...

void	pip_spawn_from_func (pip_spawn_program_t progp, char prog, char funcname, void arg, char *envv, void exp, void *aux)
	Setting information to invoke a PiP task starting from a function defined in a program. More...

void	pip_spawn_hook (pip_spawn_hook_t hook, pip_spawnhook_t before, pip_spawnhook_t after, void hookarg)
	Setting invocation hook information. More...

int	pip_task_spawn (pip_spawn_program_t progp, uint32_t coreno, uint32_t opts, int pipidp, pip_spawn_hook_t *hookp)
	Spawning a PiP task. More...

int	pip_spawn (char filename, char argv, char envv, uint32_t coreno, int pipidp, pip_spawnhook_t before, pip_spawnhook_t after, void *hookarg)
	spawn a PiP task (PiP v1 API and deprecated) More...

int	pip_blt_spawn (pip_spawn_program_t progp, uint32_t coreno, uint32_t opts, int pipidp, pip_task_t *bltp, pip_task_queue_t queue, pip_spawn_hook_t *hookp)
	spawn a PiP BLT/ULP (Bi-Level Task / User-Level Process) More...

Detailed Description

PiP Spawnig PiP (ULP/BLT) task

Description: Spawning PiP task or ULP/BLT task

Function Documentation

void pip_spawn_from_main	(	pip_spawn_program_t *	progp,
		char *	prog,
		char **	argv,
		char **	envv,
		void *	exp,
		void *	aux
	)

Name: pip_spawn_from_main

Synopsis: #include <pip/pip.h>
void pip_spawn_from_main( pip_spawn_program_t *progp, char *prog, char **argv, char **envv, void *exp, void *aux )

Description: This function sets up the pip_spawn_program_t structure for spawning a PiP task, starting from the mmain function.

Parameters

[out]	progp	Pointer to the `pip_spawn_program_t` structure in which the program invokation information will be set
[in]	prog	Path to the executiable file.
[in]	argv	Argument vector.
[in]	envv	Environment variables. If this is `NULL`, then the `environ` variable is used for the spawning PiP task.
[in]	exp	Export value to the spawning PiP task
[in]	aux	Auxiliary data to be associated with the created PiP task

See Also: pip_task_spawn; pip_spawn_from_func

void pip_spawn_from_func	(	pip_spawn_program_t *	progp,
		char *	prog,
		char *	funcname,
		void *	arg,
		char **	envv,
		void *	exp,
		void *	aux
	)

Name: pip_spawn_from_func

Synopsis: #include <pip/pip.h>
pip_spawn_from_func( pip_spawn_program_t *progp, char *prog, char *funcname, void *arg, char **envv, void *exp, void *aux );

Description: This function sets the required information to invoke a program, starting from the main() function. The function should have the function prototype as shown below;
int start_func( void *arg )

This start function must be globally defined in the program.. The returned integer of the start function will be treated in the same way as the main function. This implies that the pip_wait function family called from the PiP root can retrieve the return code.

Parameters

[out]	progp	Pointer to the `pip_spawn_program_t` structure in which the program invokation information will be set
[in]	prog	Path to the executiable file.
[in]	funcname	Function name to be started
[in]	arg	Argument which will be passed to the start function
[in]	envv	Environment variables. If this is `NULL`, then the `environ` variable is used for the spawning PiP task.
[in]	exp	Export value to the spawning PiP task
[in]	aux	Auxiliary data to be associated with the created PiP task

See Also: pip_task_spawn; pip_spawn_from_main

void pip_spawn_hook	(	pip_spawn_hook_t *	hook,
		pip_spawnhook_t	before,
		pip_spawnhook_t	after,
		void *	hookarg
	)

Name: pip_spawn_hook

Synopsis: #include <pip/pip.h>
void pip_spawn_hook( pip_spawn_hook_t *hook, pip_spawnhook_t before, pip_spawnhook_t after, void *hookarg );

Description

The before and after functions are introduced to follow the programming model of the fork and exec. before function does the prologue found between the fork and exec. after function is to free the argument if it is malloc()ed, for example.

Precondition: It should be noted that the before and after functions are called in the context of PiP root, although they are running as a part of PiP task (i.e., having PID of the spawning PiP task). Conversely speaking, those functions cannot access the variables defined in the spawning PiP task.; The before and after hook functions should have the function prototype as shown below;
int hook_func( void *hookarg )

Parameters

[out]	hook	Pointer to the `pip_spawn_hook_t` structure in which the invocation hook information will be set
[in]	before	Just before the executing of the spawned PiP task, this function is called so that file descriptors inherited from the PiP root, for example, can deal with. This is only effective with the PiP process mode. This function is called with the argument hookarg described below.
[in]	after	This function is called when the PiP task terminates for the cleanup purpose. This function is called with the argument hookarg described below.
[in]	hookarg	The argument for the before and after function call.

Note: Note that the file descriptors and signal handlers are shared between PiP root and PiP tasks in the pthread execution mode.

See Also: pip_task_spawn

int pip_task_spawn	(	pip_spawn_program_t *	progp,
		uint32_t	coreno,
		uint32_t	opts,
		int *	pipidp,
		pip_spawn_hook_t *	hookp
	)

Name: pip_task_spawn

Synopsis: #include <pip/pip.h>
int pip_task_spawn( pip_spawn_program_t *progp, uint32_t coreno, uint32_t opts, int *pipidp, pip_spawn_hook_t *hookp );

Description: This function spawns a PiP task specified by progp.

: In the process execution mode, the file descriptors having the FD_CLOEXEC flag is closed and will not be passed to the spawned PiP task. This simulated close-on-exec will not take place in the pthread execution mode.

Parameters

[out]	progp	pip_spawn_program_t
[in]	coreno	CPU core number for the PiP task to be bound to. By default, `coreno` is set to zero, for example, then the calling task will be bound to the 'first' core available. This is in mind that the available core numbers are not contiguous. To specify an absolute core number, `coreno` must be bitwise-ORed with `PIP_CPUCORE_ABS`. If `PIP_CPUCORE_ASIS` is specified, then the core binding will not take place.
[in]	opts	option flags
[in,out]	pipidp	Specify PiP ID of the spawned PiP task. If `PIP_PIPID_ANY` is specified, then the PiP ID of the spawned PiP task is up to the PiP library and the assigned PiP ID will be returned.
[in]	hookp	Hook information to be invoked before and after the program invokation.

Returns: Zero is returned if this function succeeds. On error, an error number is returned.

Return values

EPERM	PiP library is not yet initialized
EPERM	PiP task tries to spawn child task
EINVAL	`progp` is `NULL`
EINVAL	`opts` is invalid and/or unacceptable
EINVAL	the value off `pipidp` is invalid
EINVAL	the coreno is larger than or equal to `PIP_CPUCORE_CORENO_MAX`
EBUSY	specified PiP ID is alredy occupied
ENOMEM	not enough memory
ENXIO	`dlmopen` failss

Bugs: In theory, there is no reason to restrict for a PiP task to spawn another PiP task. However, the current glibc implementation does not allow to do so.

: If the root process is multithreaded, only the main thread can call this function.

See Also: pip_task_spawn; pip_spawn_from_main; pip_spawn_from_func; pip_spawn_hook; pip_spawn; pip_blt_spawn

int pip_spawn	(	char *	filename,
		char **	argv,
		char **	envv,
		uint32_t	coreno,
		int *	pipidp,
		pip_spawnhook_t	before,
		pip_spawnhook_t	after,
		void *	hookarg
	)

Name: pip_spawn

Synopsis: #include <pip/pip.h>
int pip_spawn( char *filename, char **argv, char **envv, uint32_t coreno, int *pipidp, pip_spawnhook_t before, pip_spawnhook_t after, void *hookarg);

Description: This function spawns a PiP task.

: In the process execution mode, the file descriptors having the FD_CLOEXEC flag is closed and will not be passed to the spawned PiP task. This simulated close-on-exec will not take place in the pthread execution mode.

Parameters

[in]	filename	The executable to run as a PiP task
[in]	argv	Argument(s) for the spawned PiP task
[in]	envv	Environment variables for the spawned PiP task
[in]	coreno	CPU core number for the PiP task to be bound to. By default, `coreno` is set to zero, for example, then the calling task will be bound to the first core available. This is in mind that the available core numbers are not contiguous. To specify an absolute core number, `coreno` must be bitwise-ORed with `PIP_CPUCORE_ABS`. If `PIP_CPUCORE_ASIS` is specified, then the core binding will not take place.
[in,out]	pipidp	Specify PiP ID of the spawned PiP task. If `PIP_PIPID_ANY` is specified, then the PiP ID of the spawned PiP task is up to the PiP library and the assigned PiP ID will be returned.
[in]	before	Just before the executing of the spawned PiP task, this function is called so that file descriptors inherited from the PiP root, for example, can deal with. This is only effective with the PiP process mode. This function is called with the argument hookarg described below.
[in]	after	This function is called when the PiP task terminates for the cleanup purpose. This function is called with the argument hookarg described below.
[in]	hookarg	The argument for the before and after function call.

Returns: Return 0 on success. Return an error code on error.

Return values

EPERM	PiP library is not yet initialized
EPERM	PiP task tries to spawn child task
EINVAL	`progp` is `NULL`
EINVAL	`opts` is invalid and/or unacceptable
EINVAL	the value off `pipidp` is invalid
EINVAL	the coreno is larger than or equal to `PIP_CPUCORE_CORENO_MAX`
EBUSY	specified PiP ID is alredy occupied
ENOMEM	not enough memory
ENXIO	`dlmopen` failss

Bugs: In theory, there is no reason to restrict for a PiP task to spawn another PiP task. However, the current glibc implementation does not allow to do so.

: If the root process is multithreaded, only the main thread can call this function.

See Also: pip_task_spawn; pip_spawn_from_main; pip_spawn_from_func; pip_spawn_hook; pip_task_spawn; pip_blt_spawn

int pip_blt_spawn	(	pip_spawn_program_t *	progp,
		uint32_t	coreno,
		uint32_t	opts,
		int *	pipidp,
		pip_task_t **	bltp,
		pip_task_queue_t *	queue,
		pip_spawn_hook_t *	hookp
	)

Name: pip_blt_spawn

Synopsis: #include <pip/pip.h>
int pip_blt_spawn( pip_spawn_program_t *progp, uint32_t coreno, uint32_t opts, int *pipidp, pip_task_t **bltp, pip_task_queue_t *queue, pip_spawn_hook_t *hookp );

Description: This function spawns a BLT (PiP task) specified by progp. The created annd returned BLT is another form of a PiP task. It is an opaque object, essentially a double-linked list. Thus created BLT can be enqueued or dequeued to/from a pip_task_queue_t.

: In the process execution mode, the file descriptors having the FD_CLOEXEC flag is closed and will not be passed to the spawned PiP task. This simulated close-on-exec will not take place in the pthread execution mode.

Parameters

[out]	progp	pip_spawn_program_t
[in]	coreno	CPU core number for the PiP task to be bound to. By default, `coreno` is set to zero, for example, then the calling task will be bound to the first core available. This is in mind that the available core numbers are not contiguous. To specify an absolute core number, `coreno` must be bitwise-ORed with `PIP_CPUCORE_ABS`. If `PIP_CPUCORE_ASIS` is specified, then the core binding will not take place.
[in]	opts	option flags. If `PIP_TASK_INACTIVE` is set, the created BLT is suspended and enqueued to the specified `queue`. Otherwise the BLT will schedules the BLTs in `queue`.
[in,out]	pipidp	Specify PiP ID of the spawned PiP task. If `PIP_PIPID_ANY` is specified, then the PiP ID of the spawned PiP task is up to the PiP library and the assigned PiP ID will be returned. The PiP execution mode can also be specified (see below).
[in,out]	bltp	returns created BLT
[in]	queue	PiP task queue. See the above `opts` description.
[in]	hookp	Hook information to be invoked before and after the program invokation.

Returns: Return 0 on success. Return an error code on error.

Return values

EPERM	PiP library is not yet initialized
EPERM	PiP task tries to spawn child task
EINVAL	`progp` is `NULL`
EINVAL	`opts` is invalid and/or unacceptable
EINVAL	the value off `pipidp` is invalid
EBUSY	specified PiP ID is alredy occupied
ENOMEM	not enough memory
ENXIO	`dlmopen` failss

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

Note: In theory, there is no reason to restrict for a PiP task to spawn another PiP task. However, the current implementation fails to do so. If the root process is multithreaded, only the main thread can call this function.

Environment

PIP_MODE Specifying the PiP execution mode. The value can be one of; 'process', 'process:preload', 'process:got' and 'thread' (or 'pthread').
PIP_STACKSZ Sepcifying the stack size (in bytes). The KMP_STACKSIZE and OMP_STACKSIZE can also be specified. The 't', 'g', 'm', 'k' and 'b' posfix character can be used.
PIP_STOP_ON_START Specifying the PIP ID to stop on start PiP task program to debug from the beginning. If the before hook is specified, then the PiP task will be stopped just before calling the before hook.
PIP_STACKSZ Sepcifying the stack size (in bytes). The KMP_STACKSIZE and OMP_STACKSIZE can also be specified. The 't', 'g', 'm', 'k' and 'b' posfix character can be used.

Bugs: In theory, there is no reason to restrict for a PiP task to spawn another PiP task. However, the current glibc implementation does not allow to do so.

: If the root process is multithreaded, only the main thread can call this function.

See Also: pip_task_spawn; pip_spawn_from_main; pip_spawn_from_func; pip_spawn_hook; pip_task_spawn; pip_spawn

Functions

Detailed Description

PiP Spawnig PiP (ULP/BLT) task

Function Documentation