Task Management

Task Management —

Synopsis


#include <monitor/producer/task.h>


            prod_task;
enum        prod_task_state;
enum        prod_task_flags;
void        (*prod_task_exit)               (prod_task *task);
prod_task*  prod_task_new                   (prod_task_exit cb,
                                             void *user_data);
void        prod_task_check                 (void);
void        prod_task_kill                  (prod_task *task);
int         prod_task_fork                  (prod_task *task);
int         prod_task_set_program           (prod_task *task,
                                             const char *prog_name,
                                             char *const *argv,
                                             char *const *envp);
int         prod_task_exec                  (prod_task *task,
                                             prod_exec_flags flags);
enum        prod_exec_flags;
#define     PROD_EXEC_STDINOUT

            prod_task_simple_output;
int         prod_task_exec_simple           (const char *command,
                                             prod_task_simple_output *out,
                                             mon_ctx *ctx);
int         prod_task_exec_simplev          (const char *program,
                                             char *const *argv,
                                             prod_task_simple_output *out,
                                             mon_ctx *ctx);

Description

Details

prod_task

typedef struct {
	prod_task_state		state;
	prod_task_flags		flags;

	char			*prog_name;
	char			**argv;
	char			**envp;

	int			iofd;
	int			errfd;

	pid_t			pid;
	int			exit_status;

	prod_task_exit		exit_cb;
	void			*user_data;
} prod_task;

Describes a task that will be run in a separate process.

prod_task_state `state`;	the process state. See prod_task_state.
prod_task_flags `flags`;	task flags. See prod_task_flags.
char *`prog_name`;	the name of the program to execute in the child process.
char **`argv`;	the arguments of `prog_name`.
char **`envp`;	the environment to use when executing `prog_name`.
int `iofd`;	socket connected to the child process' stdin/stdout.
int `errfd`;	socket connected to the child process' stderr.
pid_t `pid`;	ID of the child process.
int `exit_status`;	exit status of the child process.
prod_task_exit `exit_cb`;	function to call if the child process exits.
void *`user_data`;	user-specified opaque data.

enum prod_task_state

typedef enum
{
	/* Not started yet or exited and reported */
	PROD_PROC_INACTIVE,
	/* Running */
	PROD_PROC_RUNNING,
	/* Exited but not reported yet */
	PROD_PROC_DEAD
} prod_task_state;

Status of the process that is running the task.

`PROD_PROC_INACTIVE`	the task has no running process.
`PROD_PROC_RUNNING`	the task is running.
`PROD_PROC_DEAD`	the task has exited but its death is not reported yet (neither `prod_task_check()` nor `prod_task_kill()` were called for this task).

enum prod_task_flags

typedef enum
{
	PROD_TASK_AUTOFREE	= (1 << 0),
	PROD_TASK_IN_CB		= (1 << 1),
	PROD_TASK_SEND_KILL	= (1 << 2),
	PROD_TASK_MERGE_ENV	= (1 << 3)
} prod_task_flags;

Task flags.

`PROD_TASK_AUTOFREE`	free the task structure if its process terminates.
`PROD_TASK_IN_CB`	the task exit callback function is being called.
`PROD_TASK_SEND_KILL`	sending a SIGKILL has been scheduled for this task.
`PROD_TASK_MERGE_ENV`	merge the contents of `envp` into the current environment instead of replacing it.

prod_task_exit ()

void        (*prod_task_exit)               (prod_task *task);

Prototype of the process exit callback function.

task : the task descriptor belinging to the exited process.

prod_task_new ()

prod_task*  prod_task_new                   (prod_task_exit cb,
                                             void *user_data);

Allocates a new prod_task structure.

`cb` :	the function to call when the process terminates.
`user_data` :	opaque user data to be passed to `cb`.
Returns :	a new prod_task.

prod_task_check ()

void        prod_task_check                 (void);

Checks for dead processes. If a process has exited since the last call to prod_task_check(), its exit callback function is called. If the PROD_TASK_AUTOFREE flag is set after the callback function returns, the task structure is deallocated.

prod_task_kill ()

void        prod_task_kill                  (prod_task *task);

If called within a task exit callback function, it marks the task to be freed when the callback function returns. If called outside of a task exit callback function, it sends a SIGTERM to the child process. If the child process does not exit within 3 seconds, a SIGKILL is sent.

task : a prod_task.

prod_task_fork ()

int         prod_task_fork                  (prod_task *task);

Forks a child process.

Note

Just like fork(), this function returns in both the parent and the child process. The task->pid field will be set to 0 in the child process and will contain the child's process ID in the parent process.

`task` :	a prod_task.
Returns :	0 if successful or an error code.

prod_task_set_program ()

int         prod_task_set_program           (prod_task *task,
                                             const char *prog_name,
                                             char *const *argv,
                                             char *const *envp);

Sets the program name, arguments and environment for a prod_task.

`task` :	a prod_task.
`prog_name` :	the name of the program to execute in the child process.
`argv` :	the argument vector of the program.
`envp` :	the environment of the program. If `NULL`, the child inherits the current environment.
Returns :	0 if successful or an error code.

prod_task_exec ()

int         prod_task_exec                  (prod_task *task,
                                             prod_exec_flags flags);

Executes a program in a task. The program must have been set by calling prod_task_set_program() before. If the PROD_EXEC_STDINOUT bit is set in flags, a socket pair is created, one end is returned in task->iofd, the other end is bound to the new process' standard input and output. If the PROD_EXEC_STDINOUT bit is not set, the new process' standard input and output is redirected from/to /dev/null. The same rules apply for the PROD_EXEC_STDERR bit and the child process' standard error.

`task` :	a prod_task.
`flags` :	one or more of prod_exec_flags.
Returns :	0 if successful or an error code.

enum prod_exec_flags

typedef enum
{
	PROD_EXEC_STDIN		= (1 << 0),
	PROD_EXEC_STDOUT	= (1 << 1),
	PROD_EXEC_STDERR	= (1 << 2)
} prod_exec_flags;

Flags controlling the execution environment of a program.

`PROD_EXEC_STDIN`	set up a pipe for stdin.
`PROD_EXEC_STDOUT`	set up a pipe for stdout.
`PROD_EXEC_STDERR`	set up a pipe for stderr.

PROD_EXEC_STDINOUT

#define PROD_EXEC_STDINOUT	(PROD_EXEC_STDIN | PROD_EXEC_STDOUT)

Combines PROD_EXEC_STDIN and PROD_EXEC_STDOUT.

prod_task_simple_output

typedef struct {
	GString			out;
	GString			err;
	int			exit_status;
} prod_task_simple_output;

Holds the result of the execution of a simple command.

GString `out`;	contains the program's standard output.
GString `err`;	contains the program's standard error.
int `exit_status`;	the exit status of the program.

prod_task_exec_simple ()

int         prod_task_exec_simple           (const char *command,
                                             prod_task_simple_output *out,
                                             mon_ctx *ctx);

Executes a simple command. The ctx context is resumed when the command exits.

`command` :	the command to execute.
`out` :	pointer to a prod_task_simple_output that will hold the program's output.
`ctx` :	a mon_ctx.
Returns :	`MON_CONTINUE` if the program has started or an error code.

prod_task_exec_simplev ()

int         prod_task_exec_simplev          (const char *program,
                                             char *const *argv,
                                             prod_task_simple_output *out,
                                             mon_ctx *ctx);

Executes a simple command. The ctx context is resumed when the command exits.

`program` :	the name of the program to execute.
`argv` :	arguments of the program.
`out` :	pointer to a prod_task_simple_output that will hold the program's output.
`ctx` :	a mon_ctx.
Returns :	`MON_CONTINUE` if the program has started or an error code.