:orphan:

.. index:: pair: group; TAPI Job Methods (tapi_job_methods)
.. _doxid-group__tapi__job__methods:

TAPI Job Methods (tapi_job_methods)
===================================

.. toctree::
	:hidden:

	struct_tapi_job_methods_t.rst

Overview
~~~~~~~~

Functions that TAPI Job backend might implement. :ref:`More...<details-group__tapi__job__methods>`


.. ref-code-block:: cpp
	:class: doxyrest-overview-code-block

	
	// typedefs

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>`() :ref:`tapi_job_method_create<doxid-group__tapi__job__methods_1ga23c5a83491412bd57c436b83751b146f>`(
		tapi_job_t *job,
		const char *spawner,
		const char *program,
		const char **argv,
		const char **env
		);

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>`() :ref:`tapi_job_method_start<doxid-group__tapi__job__methods_1ga8d32cb3fcafea43a9c4b41ddf7c5893d>`(const tapi_job_t *job);

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>`() :ref:`tapi_job_method_allocate_channels<doxid-group__tapi__job__methods_1gad7a5d99921de1c9f6cd1eebeb9a04a1e>`(
		const tapi_job_t *job,
		bool input_channels,
		unsigned int n_channels,
		unsigned int *channels
		);

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>`() :ref:`tapi_job_method_kill<doxid-group__tapi__job__methods_1gaf8102ad590269a444dd1f2467103c8e1>`(
		const tapi_job_t *job,
		int signo
		);

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>`() :ref:`tapi_job_method_killpg<doxid-group__tapi__job__methods_1ga07f6b33110a2408a66190d4d0c06a8ca>`(
		const tapi_job_t *job,
		int signo
		);

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>`() :ref:`tapi_job_method_wait<doxid-group__tapi__job__methods_1gac80c60db0e97fc61a08a7a97a688ca20>`(
		const tapi_job_t *job,
		int timeout_ms,
		tapi_job_status_t *status
		);

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>`() :ref:`tapi_job_method_stop<doxid-group__tapi__job__methods_1ga1c9a9975b044510cc5c1f94604442368>`(
		const tapi_job_t *job,
		int signo,
		int term_timeout_ms
		);

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>`() :ref:`tapi_job_method_destroy<doxid-group__tapi__job__methods_1ga1338f6840b49b2efd82e7fdc78acadd3>`(
		const tapi_job_t *job,
		int term_timeout_ms
		);

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>`() :ref:`tapi_job_method_set_workdir<doxid-group__tapi__job__methods_1ga1e717c4770a3bd2a5bdba5983f84b720>`(
		const tapi_job_t *job,
		const char *dir
		);

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>`() :ref:`tapi_job_method_wrapper_add<doxid-group__tapi__job__methods_1ga1a52c6791b2e4e4de3fba49c0b7476b2>`(
		const tapi_job_t *job,
		const char *tool,
		const char **argv,
		tapi_job_wrapper_priority_t priority,
		unsigned int *wrapper_id
		);

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>`() :ref:`tapi_job_method_wrapper_delete<doxid-group__tapi__job__methods_1gaedebe51989501175c249bdebd8c9c560>`(
		const tapi_job_t *job,
		unsigned int wrapper_id
		);

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>`() :ref:`tapi_job_method_add_exec_param<doxid-group__tapi__job__methods_1ga1b35ba7a6aa609c8eaa975bbaaac9c38>`(
		const tapi_job_t *job,
		tapi_job_exec_param *exec_param
		);

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>`() :ref:`tapi_job_method_add_sched_param<doxid-group__tapi__job__methods_1ga64f14dac2a84caf2c291bf8032d2a5a7>`(
		const tapi_job_t *job,
		tapi_job_sched_param *sched_param
		);

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>`() :ref:`tapi_job_method_set_autorestart<doxid-group__tapi__job__methods_1gaaab583fd53084cc880e3f489ce5fdf37>`(
		const tapi_job_t *job,
		unsigned int value
		);

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>`() :ref:`tapi_job_method_get_autorestart<doxid-group__tapi__job__methods_1ga1a6d3ffa3640e9e2351d4313e1c2c624>`(
		const tapi_job_t *job,
		unsigned int *value
		);

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>`() :ref:`tapi_job_method_recreate<doxid-group__tapi__job__methods_1ga4c20c26419a89e6a9e6779986eb37bc7>`(
		tapi_job_t *job,
		const void *identifier
		);

	typedef struct :ref:`tapi_job_methods_t<doxid-structtapi__job__methods__t>` :ref:`tapi_job_methods_t<doxid-group__tapi__job__methods_1gad147b028131e9c24f3cebb9040b8d2f7>`;

	// structs

	struct :ref:`tapi_job_methods_t<doxid-structtapi__job__methods__t>`;

.. _details-group__tapi__job__methods:

Detailed Documentation
~~~~~~~~~~~~~~~~~~~~~~

Functions that TAPI Job backend might implement.

Typedefs
--------

.. index:: pair: typedef; tapi_job_method_create
.. _doxid-group__tapi__job__methods_1ga23c5a83491412bd57c436b83751b146f:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>`() 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



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

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



.. rubric:: Returns:

Status code

.. index:: pair: typedef; tapi_job_method_start
.. _doxid-group__tapi__job__methods_1ga8d32cb3fcafea43a9c4b41ddf7c5893d:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>`() tapi_job_method_start(const tapi_job_t *job)

Method that starts a job



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- job

		- Job instance handle



.. rubric:: Returns:

Status code

.. index:: pair: typedef; tapi_job_method_allocate_channels
.. _doxid-group__tapi__job__methods_1gad7a5d99921de1c9f6cd1eebeb9a04a1e:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>`() 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.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- 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)



.. rubric:: Returns:

Status code

.. index:: pair: typedef; tapi_job_method_kill
.. _doxid-group__tapi__job__methods_1gaf8102ad590269a444dd1f2467103c8e1:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>`() tapi_job_method_kill(
		const tapi_job_t *job,
		int signo
		)

Method that sends a signal to a job



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- job

		- Job instance handle

	*
		- signo

		- Signal number



.. rubric:: Returns:

Status code

.. index:: pair: typedef; tapi_job_method_killpg
.. _doxid-group__tapi__job__methods_1ga07f6b33110a2408a66190d4d0c06a8ca:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>`() tapi_job_method_killpg(
		const tapi_job_t *job,
		int signo
		)

Method that sends a signal to job's process group



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- job

		- Job instance handle

	*
		- signo

		- Signal number



.. rubric:: Returns:

Status code

.. index:: pair: typedef; tapi_job_method_wait
.. _doxid-group__tapi__job__methods_1gac80c60db0e97fc61a08a7a97a688ca20:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>`() 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



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- 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



.. rubric:: Returns:

Status code

.. index:: pair: typedef; tapi_job_method_stop
.. _doxid-group__tapi__job__methods_1ga1c9a9975b044510cc5c1f94604442368:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>`() 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``.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- 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).



.. rubric:: Returns:

Status code

.. index:: pair: typedef; tapi_job_method_destroy
.. _doxid-group__tapi__job__methods_1ga1338f6840b49b2efd82e7fdc78acadd3:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>`() 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.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- 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).



.. rubric:: Returns:

Status code

.. index:: pair: typedef; tapi_job_method_set_workdir
.. _doxid-group__tapi__job__methods_1ga1e717c4770a3bd2a5bdba5983f84b720:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>`() tapi_job_method_set_workdir(
		const tapi_job_t *job,
		const char *dir
		)

Method that sets working directory.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- job

		- Job instance handle

	*
		- dir

		- Job's working directory after start.



.. rubric:: Returns:

Status code

.. index:: pair: typedef; tapi_job_method_wrapper_add
.. _doxid-group__tapi__job__methods_1ga1a52c6791b2e4e4de3fba49c0b7476b2:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>`() 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



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- job

		- Job instance handle

	*
		- tool

		- Path to the wrapper tool

	*
		- argv

		- Wrapper arguments (last item is ``NULL``)

	*
		- priority

		- Wrapper priority

	*
		- wrapper_id

		- Wrapper handle



.. rubric:: Returns:

Status code

.. index:: pair: typedef; tapi_job_method_wrapper_delete
.. _doxid-group__tapi__job__methods_1gaedebe51989501175c249bdebd8c9c560:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>`() tapi_job_method_wrapper_delete(
		const tapi_job_t *job,
		unsigned int wrapper_id
		)

Method that deletes the wrapper instance handle



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- job

		- Job instance handle

	*
		- wrapper_id

		- Wrapper instance handle



.. rubric:: Returns:

Status code

.. index:: pair: typedef; tapi_job_method_add_exec_param
.. _doxid-group__tapi__job__methods_1ga1b35ba7a6aa609c8eaa975bbaaac9c38:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>`() 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



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- 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``.



.. rubric:: Returns:

Status code

.. index:: pair: typedef; tapi_job_method_add_sched_param
.. _doxid-group__tapi__job__methods_1ga64f14dac2a84caf2c291bf8032d2a5a7:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>`() 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

.. index:: pair: typedef; tapi_job_method_set_autorestart
.. _doxid-group__tapi__job__methods_1gaaab583fd53084cc880e3f489ce5fdf37:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>`() 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.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- job

		- Job instance handle

	*
		- value

		- Autorestart timeout in seconds or ``0`` to disable autorestart for the process



.. rubric:: Returns:

Status code

.. index:: pair: typedef; tapi_job_method_get_autorestart
.. _doxid-group__tapi__job__methods_1ga1a6d3ffa3640e9e2351d4313e1c2c624:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>`() tapi_job_method_get_autorestart(
		const tapi_job_t *job,
		unsigned int *value
		)

Method that obtains the autorestart timeout



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- job

		- Job instance handle

	*
		- value

		- Autorestart timeout in seconds. If ``0``, the autorestart is disabled.



.. rubric:: Returns:

Status code

.. index:: pair: typedef; tapi_job_method_recreate
.. _doxid-group__tapi__job__methods_1ga4c20c26419a89e6a9e6779986eb37bc7:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>`() 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.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- 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



.. rubric:: Returns:

Status code

.. index:: pair: typedef; tapi_job_methods_t
.. _doxid-group__tapi__job__methods_1gad147b028131e9c24f3cebb9040b8d2f7:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef struct :ref:`tapi_job_methods_t<doxid-structtapi__job__methods__t>` tapi_job_methods_t

Methods to operate TAPI Job instances