SimGrid  3.20
Versatile Simulation of Distributed Systems
Process Management Functions

Detailed Description

This section describes the process structure of MSG (msg_process_t) and the functions for managing it.

Processes (msg_process_t) are independent agents that can do stuff on their own.

They are in charge of executing your code interacting with the simulated world. A process may be defined as a code with some private data. Processes must be located on hosts (msg_host_t), and they exchange data by sending tasks (msg_task_t) that are similar to envelops containing data.

Functions

sg_host_t sg_host_self ()
 Return the location on which a process is running. More...
 
msg_process_t MSG_process_create (const char *name, xbt_main_func_t code, void *data, msg_host_t host)
 Creates and runs a new msg_process_t. More...
 
msg_process_t MSG_process_create_with_arguments (const char *name, xbt_main_func_t code, void *data, msg_host_t host, int argc, char **argv)
 Creates and runs a new msg_process_t. More...
 
msg_process_t MSG_process_create_with_environment (const char *name, xbt_main_func_t code, void *data, msg_host_t host, int argc, char **argv, xbt_dict_t properties)
 Creates and runs a new msg_process_t. More...
 
voidMSG_process_get_data (msg_process_t process)
 Returns the user data of a process. More...
 
msg_error_t MSG_process_set_data (msg_process_t process, void *data)
 Sets the user data of a process. More...
 
void MSG_process_set_data_cleanup (void_f_pvoid_t data_cleanup)
 Sets a cleanup function to be called to free the userdata of a process when a process is destroyed. More...
 
int MSG_process_self_PID ()
 Return the PID of the current process. More...
 
int MSG_process_self_PPID ()
 Return the PPID of the current process. More...
 
const char * MSG_process_self_name ()
 Return the name of the current process. More...
 
msg_process_t MSG_process_self ()
 Return the current process. More...
 
void MSG_process_on_exit (int_f_pvoid_pvoid_t fun, void *data)
 Add a function to the list of "on_exit" functions for the current process. More...
 
void MSG_process_ref (msg_process_t process)
 Take an extra reference on that process to prevent it to be garbage-collected. More...
 
void MSG_process_unref (msg_process_t process)
 Release a reference on that process so that it can get be garbage-collected. More...
 

Function Documentation

◆ sg_host_self()

sg_host_t sg_host_self ( )

Return the location on which a process is running.

Returns
the sg_host_t corresponding to the location on which process is running.

◆ MSG_process_create()

msg_process_t MSG_process_create ( const char *  name,
xbt_main_func_t  code,
void data,
msg_host_t  host 
)

Creates and runs a new msg_process_t.

Does exactly the same as MSG_process_create_with_arguments but without providing standard arguments (argc, argv, start_time, kill_time).

See also
MSG_process_create_with_arguments

◆ MSG_process_create_with_arguments()

msg_process_t MSG_process_create_with_arguments ( const char *  name,
xbt_main_func_t  code,
void data,
msg_host_t  host,
int  argc,
char **  argv 
)

Creates and runs a new msg_process_t.

A constructor for msg_process_t taking four arguments and returning the corresponding object. The structure (and the corresponding thread) is created, and put in the list of ready process.

Parameters
namea name for the object. It is for user-level information and can be nullptr.
codeis a function describing the behavior of the process. It should then only use functions described in Process Management Functions (to create a new msg_process_t for example), in Host Management Functions (only the read-only functions i.e. whose name contains the word get), in Task Management Functions (to create or destroy some msg_task_t for example) and in Task Actions (to handle file transfers and task processing).
dataa pointer to any data one may want to attach to the new object. It is for user-level information and can be nullptr. It can be retrieved with the function MSG_process_get_data.
hostthe location where the new process is executed.
argcfirst argument passed to code
argvsecond argument passed to code
See also
msg_process_t
Returns
The new corresponding object.

◆ MSG_process_create_with_environment()

msg_process_t MSG_process_create_with_environment ( const char *  name,
xbt_main_func_t  code,
void data,
msg_host_t  host,
int  argc,
char **  argv,
xbt_dict_t  properties 
)

Creates and runs a new msg_process_t.

A constructor for msg_process_t taking four arguments and returning the corresponding object. The structure (and the corresponding thread) is created, and put in the list of ready process.

Parameters
namea name for the object. It is for user-level information and can be nullptr.
codeis a function describing the behavior of the process. It should then only use functions described in Process Management Functions (to create a new msg_process_t for example), in Host Management Functions (only the read-only functions i.e. whose name contains the word get), in Task Management Functions (to create or destroy some msg_task_t for example) and in Task Actions (to handle file transfers and task processing).
dataa pointer to any data one may want to attach to the new object. It is for user-level information and can be nullptr. It can be retrieved with the function MSG_process_get_data.
hostthe location where the new process is executed.
argcfirst argument passed to code
argvsecond argument passed to code. WARNING, these strings are freed by the SimGrid kernel when the process exits, so they cannot be static nor shared between several processes.
propertieslist a properties defined for this process
See also
msg_process_t
Returns
The new corresponding object.

◆ MSG_process_get_data()

void* MSG_process_get_data ( msg_process_t  process)

Returns the user data of a process.

This function checks whether process is a valid pointer and returns the user data associated to this process.

◆ MSG_process_set_data()

msg_error_t MSG_process_set_data ( msg_process_t  process,
void data 
)

Sets the user data of a process.

This function checks whether process is a valid pointer and sets the user data associated to this process.

◆ MSG_process_set_data_cleanup()

void MSG_process_set_data_cleanup ( void_f_pvoid_t  data_cleanup)

Sets a cleanup function to be called to free the userdata of a process when a process is destroyed.

Parameters
data_cleanupa cleanup function for the userdata of a process, or nullptr to call no function

◆ MSG_process_self_PID()

int MSG_process_self_PID ( )

Return the PID of the current process.

This function returns the PID of the currently running msg_process_t.

◆ MSG_process_self_PPID()

int MSG_process_self_PPID ( )

Return the PPID of the current process.

This function returns the PID of the parent of the currently running msg_process_t.

◆ MSG_process_self_name()

const char* MSG_process_self_name ( )

Return the name of the current process.

◆ MSG_process_self()

msg_process_t MSG_process_self ( )

Return the current process.

This function returns the currently running msg_process_t.

◆ MSG_process_on_exit()

void MSG_process_on_exit ( int_f_pvoid_pvoid_t  fun,
void data 
)

Add a function to the list of "on_exit" functions for the current process.

The on_exit functions are the functions executed when your process is killed. You should use them to free the data used by your process.

◆ MSG_process_ref()

void MSG_process_ref ( msg_process_t  process)

Take an extra reference on that process to prevent it to be garbage-collected.

◆ MSG_process_unref()

void MSG_process_unref ( msg_process_t  process)

Release a reference on that process so that it can get be garbage-collected.