TAPI Job Methods (tapi_job_methods)

Overview

Functions that TAPI Job backend might implement. More…

// typedefs

typedef te_errno() tapi_job_method_create(
    tapi_job_t *job,
    const char *spawner,
    const char *program,
    const char **argv,
    const char **env
    );

typedef te_errno() tapi_job_method_start(const tapi_job_t *job);

typedef te_errno() tapi_job_method_allocate_channels(
    const tapi_job_t *job,
    bool input_channels,
    unsigned int n_channels,
    unsigned int *channels
    );

typedef te_errno() tapi_job_method_kill(
    const tapi_job_t *job,
    int signo
    );

typedef te_errno() tapi_job_method_killpg(
    const tapi_job_t *job,
    int signo
    );

typedef te_errno() tapi_job_method_wait(
    const tapi_job_t *job,
    int timeout_ms,
    tapi_job_status_t *status
    );

typedef te_errno() tapi_job_method_stop(
    const tapi_job_t *job,
    int signo,
    int term_timeout_ms
    );

typedef te_errno() tapi_job_method_destroy(
    const tapi_job_t *job,
    int term_timeout_ms
    );

typedef te_errno() tapi_job_method_set_workdir(
    const tapi_job_t *job,
    const char *dir
    );

typedef te_errno() tapi_job_method_wrapper_add(
    const tapi_job_t *job,
    const char *tool,
    const char **argv,
    tapi_job_wrapper_priority_t priority,
    unsigned int *wrapper_id
    );

typedef te_errno() tapi_job_method_wrapper_delete(
    const tapi_job_t *job,
    unsigned int wrapper_id
    );

typedef te_errno() tapi_job_method_add_exec_param(
    const tapi_job_t *job,
    tapi_job_exec_param *exec_param
    );

typedef te_errno() tapi_job_method_add_sched_param(
    const tapi_job_t *job,
    tapi_job_sched_param *sched_param
    );

typedef te_errno() tapi_job_method_set_autorestart(
    const tapi_job_t *job,
    unsigned int value
    );

typedef te_errno() tapi_job_method_get_autorestart(
    const tapi_job_t *job,
    unsigned int *value
    );

typedef te_errno() tapi_job_method_recreate(
    tapi_job_t *job,
    const void *identifier
    );

typedef struct tapi_job_methods_t tapi_job_methods_t;

// structs

struct tapi_job_methods_t;

Detailed Documentation

Functions that TAPI Job backend might implement.

Typedefs

typedef te_errno() tapi_job_method_create(
    tapi_job_t *job,
    const char *spawner,
    const char *program,
    const char **argv,
    const char **env
    )

Method that creates a job on backend side

Parameters:

job	Job instance handle. On input, job factory must be set. On output, backend specific data for the job will be set.
spawner	Spawner plugin name (may be `NULL` for the default plugin)
program	Program path to run
argv	Program arguments (last item is `NULL`)
env	Program environment (last item is `NULL`). May be `NULL` to keep the current environment.

Returns:

Status code

typedef te_errno() tapi_job_method_start(const tapi_job_t *job)

Method that starts a job

Parameters:

job	Job instance handle

Returns:

Status code

typedef te_errno() tapi_job_method_allocate_channels(
    const tapi_job_t *job,
    bool input_channels,
    unsigned int n_channels,
    unsigned int *channels
    )

Method that allocates n_channels channels. If the input_channels is true, the first channel is expected to be connected to the job’s stdin; If the input_channels is false, The first and the second output channels are expected to be connected to stdout and stderr respectively; The wiring of not mentioned channels is spawner-dependant.

Parameters:

job	Job instance handle
input_channels	`true` to allocate input channels, `false` to allocate output channels
n_channels	Number of channels
channels	A vector of obtained channel handles (may be `NULL` if the caller is not interested in the handles)

Returns:

Status code

typedef te_errno() tapi_job_method_kill(
    const tapi_job_t *job,
    int signo
    )

Method that sends a signal to a job

Parameters:

job	Job instance handle
signo	Signal number

Returns:

Status code

typedef te_errno() tapi_job_method_killpg(
    const tapi_job_t *job,
    int signo
    )

Method that sends a signal to job’s process group

Parameters:

job	Job instance handle
signo	Signal number

Returns:

Status code

typedef te_errno() tapi_job_method_wait(
    const tapi_job_t *job,
    int timeout_ms,
    tapi_job_status_t *status
    )

Method that waits for the job completion (or checks its status if timeout is zero)

Some implementations may also return zero if the job was never started

Parameters:

job	Job instance handle
timeout_ms	Timeout in ms. Meaning of negative timeout is implementation-dependent.
status	Exit status
TE_EINPROGRESS	Job is still running
TE_ECHILD	Job was never started

Returns:

Status code

typedef te_errno() tapi_job_method_stop(
    const tapi_job_t *job,
    int signo,
    int term_timeout_ms
    )

Method that stops a job. The function tries to terminate the job with the specified signal. If the signal fails to terminate the job, the function will send SIGKILL.

Parameters:

job	Job instance handle
signo	Signal to be sent at first. If signo is `SIGKILL`, it will be sent only once.
term_timeout_ms	The timeout of graceful termination of a job, if it has been running. After the timeout expiration the job will be killed with `SIGKILL` (negative means default timeout).

Returns:

Status code

typedef te_errno() tapi_job_method_destroy(
    const tapi_job_t *job,
    int term_timeout_ms
    )

Method that destroys a job on backend side. If the job has started, it is terminated as gracefully as possible. All resources of the instance are freed.

Parameters:

job	Job instance handle
term_timeout_ms	The timeout of graceful termination of a job, if it has been running. After the timeout expiration the job will be killed with `SIGKILL` (negative means default timeout).

Returns:

Status code

typedef te_errno() tapi_job_method_set_workdir(
    const tapi_job_t *job,
    const char *dir
    )

Method that sets working directory.

Parameters:

job	Job instance handle
dir	Job’s working directory after start.

Returns:

Status code

typedef te_errno() tapi_job_method_wrapper_add(
    const tapi_job_t *job,
    const char *tool,
    const char **argv,
    tapi_job_wrapper_priority_t priority,
    unsigned int *wrapper_id
    )

Method that adds a wrapper for the specified job

Parameters:

job	Job instance handle
tool	Path to the wrapper tool
argv	Wrapper arguments (last item is `NULL`)
priority	Wrapper priority
wrapper_id	Wrapper handle

Returns:

Status code

typedef te_errno() tapi_job_method_wrapper_delete(
    const tapi_job_t *job,
    unsigned int wrapper_id
    )

Method that deletes the wrapper instance handle

Parameters:

job	Job instance handle
wrapper_id	Wrapper instance handle

Returns:

Status code

typedef te_errno() tapi_job_method_add_exec_param(
    const tapi_job_t *job,
    tapi_job_exec_param *exec_param
    )

Method that adds a process parameters for the specified job

Parameters:

job	Job instance handle
exec_param	Array of process parameters. The last element must have the type TAPI_JOB_EXEC_END and data pointer to `NULL`.

Returns:

Status code

typedef te_errno() tapi_job_method_add_sched_param(
    const tapi_job_t *job,
    tapi_job_sched_param *sched_param
    )

Use tapi_job_method_add_exec_param in the new code

Deprecated

typedef te_errno() tapi_job_method_set_autorestart(
    const tapi_job_t *job,
    unsigned int value
    )

Method that sets autorestart timeout. The value represents a frequency with which the autorestart subsystem will check whether the job stopped running (regardless of the reason) and restart it if it did.

Parameters:

job	Job instance handle
value	Autorestart timeout in seconds or `0` to disable autorestart for the process

Returns:

Status code

typedef te_errno() tapi_job_method_get_autorestart(
    const tapi_job_t *job,
    unsigned int *value
    )

Method that obtains the autorestart timeout

Parameters:

job	Job instance handle
value	Autorestart timeout in seconds. If `0`, the autorestart is disabled.

Returns:

Status code

typedef te_errno() tapi_job_method_recreate(
    tapi_job_t *job,
    const void *identifier
    )

Method that retrieves information about a job that was once created and hasn’t been destroyed.

Parameters:

job	Job instance handle. On input, job factory must be set. On ouput, job is filled with the retrieved data.
identifier	Backend-specific data that allows to identify the job. For instance, it may be a name of the job for the Configurator backend.
TE_ENOENT	The job with the `identifier` was never created

Returns:

Status code

typedef struct tapi_job_methods_t tapi_job_methods_t

Methods to operate TAPI Job instances