PiP - Process-in-Process
Files
libpip

the PiP library More...

Files

file  pip.h
int pip_init (int *pipidp, int *ntasks, void **root_expp, int opts)
 Initialize the PiP library.
int pip_fin (void)
 finalize the PiP library.
int pip_spawn (char *filename, char **argv, char **envv, int coreno, int *pipidp, pip_spawnhook_t before, pip_spawnhook_t after, void *hookarg)
 spawn a PiP task
int pip_export (void *exp)
 export a memory region of the calling PiP root or a PiP task to the others.
int pip_import (int pipid, void **expp)
 import the exposed memory region of the other.
int pip_get_addr (int pipid, const char *symnam, void **addrp)
 import the exposed memory region of the other.
int pip_get_pipid (int *pipidp)
 get PIPID
int pip_get_ntasks (int *ntasksp)
 get the maximum number of the PiP tasks
int pip_isa_piptask (void)
 check if the calling task is a PiP task or not
int pip_get_mode (int *modep)
 get the PiP execution mode
int pip_exit (int retval)
 terminate PiP task
int pip_wait (int pipid, int *retval)
 wait for the termination of a PiP task
int pip_trywait (int pipid, int *retval)
 wait for the termination of a PiP task in a non-blocking way
int pip_kill (int pipid, int signal)
 deliver a signal to a PiP task
int pip_get_id (int pipid, intptr_t *idp)
 deliver a process or thread ID
const char * pip_get_mode_str (void)
 get a string of the current execution mode
void pip_barrier_init (pip_barrier_t *barrp, int n)
 initialize barrier synchronization structure
void pip_barrier_wait (pip_barrier_t *barrp)
 wait on barrier synchronization in a busy-wait way

Detailed Description

the PiP library


Function Documentation

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

Initialize the PiP library.

Parameters:
[out]pipidpWhen this is called by the PiP root process, then this returns PIP_PIPID_ROOT, otherwise it returns the PIPID of the calling PiP task.
[in,out]ntasksWhen 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_exppIf the root PiP is ready to export a memory region to any PiP task(s), then this parameter points to the variable holding the exporting address of the root PiP. 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 exporting address of the PiP root, if any.
[in]optsThis must be zero at the point of this writing.
Returns:
Return 0 on success. Return an error code on error.

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.

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 (GLIBC).

See also:
pip_export(3), pip_fin(3)
int pip_fin ( void  )

finalize the PiP library.

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

This function finalize the PiP library.

See also:
pip_init(3)
int pip_spawn ( char *  filename,
char **  argv,
char **  envv,
int  coreno,
int *  pipidp,
pip_spawnhook_t  before,
pip_spawnhook_t  after,
void *  hookarg 
)

spawn a PiP task

Parameters:
[in]filenameThe executable to run as a PiP task
[in]argvArgument(s) for the spawned PiP task
[in]envvEnvironment variables for the spawned PiP task
[in]corenoCore number for the PiP task to be bound to. If PIP_CPUCORE_ASIS is specified, then the core binding will not take place.
[in,out]pipidpSpecify PIPID of the spawned PiP task. If PIP_PIPID_ANY is specified, then the PIPID of the spawned PiP task is up to the PiP library and the assigned PIPID will be returned.
[in]beforeJust 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]afterThis function is called when the PiP task terminates for the cleanup purpose. This function is called with the argument hookarg described below.
[in]hookargThe argument for the before and after function call.
Returns:
Return 0 on success. Return an error code on error.

This function is to spawn a PiP task. These functions are introduced to follow the programming style of conventional 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. Note that the before and after functions are called in the different context from the spawned PiP task. More specifically, any variables defined in the spawned PiP task cannot be accessible from the before and after functions.

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.
int pip_export ( void *  exp)

export a memory region of the calling PiP root or a PiP task to the others.

Parameters:
[in]expStarting address of a memory region of the calling process or task to the others. function call.
Returns:
Return 0 on success. Return an error code on error.

The PiP root or a PiP task can export a memory region only once.

Note:
There is no size parameter to specify the length of the exported region because there is no way to restrict the access outside of the exported region.
See also:
pip_import(3)
int pip_import ( int  pipid,
void **  expp 
)

import the exposed memory region of the other.

Parameters:
[in]pipidThe PIPID to import the exposed address
[out]exppThe starting address of the exposed region of the PiP task specified by the pipid.
Returns:
Return 0 on success. Return an error code on error.
Note:
It is the users' responsibility to synchronize. When the target region is not exported yet , then this function returns NULL. If the root exports its region by the pip_init function call, then it is guaranteed to be imported by PiP tasks at any time.
See also:
pip_export(3)
int pip_get_addr ( int  pipid,
const char *  symnam,
void **  addrp 
)

import the exposed memory region of the other.

Parameters:
[in]pipidThe PIPID to import the exposed address
[in]symnamThe name of a symbol existing in the specified PiP task
[out]addrpThe address of the variable of the PiP task specified by the pipid.
Returns:
Return 0 on success. Return an error code on error.
Note:
pip_get_addr() function is unable to get proper addresses for local (static) or TLS variables.
Although the pip_get_addr() fucntion can be used to get a function address, calling the function of the other PiP task by its address is very tricky and it may result in an unexpected bahavior.
By definition of the dlsym() Glibc function, this may return NULL even if the variable having the specified name exists.
int pip_get_pipid ( int *  pipidp)

get PIPID

Parameters:
[out]pipidpThis parameter points to the variable which will be set to the PIPID of the calling process.
Returns:
Return 0 on success. Return an error code on error.
int pip_get_ntasks ( int *  ntasksp)

get the maximum number of the PiP tasks

Parameters:
[out]ntaskspThis parameter points to the variable which will be set to the maximum number of the PiP tasks.
Returns:
Return 0 on success. Return an error code on error.
int pip_isa_piptask ( void  )

check if the calling task is a PiP task or not

Returns:
Return 0 on success. Return an error code on error.
Note:
Unlike most of the other PiP functions, this can be called BEFORE calling the pip_init() function.
int pip_get_mode ( int *  modep)

get the PiP execution mode

Parameters:
[out]modepThis parameter points to the variable which will be set to the PiP execution mode
Returns:
Return 0 on success. Return an error code on error.
int pip_exit ( int  retval)

terminate PiP task

Parameters:
[in]retvalTerminate PiP task with the exit number specified with this parameter.
Note:
This function can be used regardless to the PiP execution mode.
Returns:
Return 0 on success. Return an error code on error.
int pip_wait ( int  pipid,
int *  retval 
)

wait for the termination of a PiP task

Parameters:
[in]pipidPIPID to wait for.
[out]retvalExit value of the terminated PiP task
Note:
This function never returns when it succeeds.
This function can be used regardless to the PiP execution mode. However, only the least significant 2 bytes are effective. This is because of the compatibility with the exit glibc function.
Returns:
Return 0 on success. Return an error code on error.
int pip_trywait ( int  pipid,
int *  retval 
)

wait for the termination of a PiP task in a non-blocking way

Parameters:
[in]pipidPIPID to wait for.
[out]retvalExit value of the terminated PiP task
Note:
This function can be used regardless to the PiP execution mode.
Returns:
Return 0 on success. Return an error code on error.
int pip_kill ( int  pipid,
int  signal 
)

deliver a signal to a PiP task

Parameters:
[out]pipidPIPID of a target PiP task
[out]signalsignal number to be delivered
Note:
This function can be used regardless to the PiP execution mode.
Returns:
Return 0 on success. Return an error code on error.
int pip_get_id ( int  pipid,
intptr_t *  idp 
)

deliver a process or thread ID

Parameters:
[out]pipidPIPID of a target PiP task
[out]idpa pointer to store the ID value
Note:
This function can be used regardless to the PiP execution mode.
Returns:
Return 0 on success. Return an error code on error.
const char* pip_get_mode_str ( void  )

get a string of the current execution mode

Note:
This function can be used regardless to the PiP execution mode.
Returns:
Return the name string of the current execution mode
void pip_barrier_init ( pip_barrier_t *  barrp,
int  n 
)

initialize barrier synchronization structure

Parameters:
[in]barrppointer to a PiP barrier structure
[in]nnumber of participants of this barrier synchronization
void pip_barrier_wait ( pip_barrier_t *  barrp)

wait on barrier synchronization in a busy-wait way

Parameters:
[in]barrppointer to a PiP barrier structure
Note:
This barrier synchronization never blocks.
 All Files Functions