.. _TaskHandler:

TaskHandler
===========

.. cpp:namespace:: pilot::TaskHandler

Module
------

The `TaskHandler` module allows the execution of a sequence of tasks, specified by a Lua script,
which can either be written by hand or generated by using the grahpical programming interface :ref:`TaskEditor`.

See :ref:`LUA_script` for more information on how to write a script by hand.

Most functions require a special permission, see :ref:`pilot.permission_e`.


Functions
---------

Common Parameters
^^^^^^^^^^^^^^^^^

``Hash64 jobid``
	Optional job id, to identify a new program execution.
	If not specified (or set to zero) will generate a new random id. See :ref:`vnx.Hash64`.

Execute Functions
^^^^^^^^^^^^^^^^^

The following functions will cancel any running program beforehand, start to execute the new program and return immediately.

.. cpp:function:: void execute_file(string filename, Hash64 jobid)
	
	Starts to execute the specified Lua script file. The ``filename`` is relative to ``~/pilot/``.
	Requires permission ``EXECUTE_SCRIPT``.
	
.. cpp:function:: void execute_program(string program, Hash64 jobid)
	
	Starts to execute the given Lua script code.
	Requires permission ``UPLOAD_SCRIPT``.
	
Intervene Functions
^^^^^^^^^^^^^^^^^^^

.. cpp:function:: void cancel_program()
	
	Will cancel a running program at the next opportunity, usually after finishing the current task.
	Requires permission ``INTERVENE_SCRIPT``.
	
.. cpp:function:: void pause_program()
	
	Will pause a running program at the next opportunity, usually after finishing the current task.
	Requires permission ``INTERVENE_SCRIPT``.
	
.. cpp:function:: void resume_program()
	
	Will resume executing a paused program.
	Requires permission ``INTERVENE_SCRIPT``.