Executor Modules
================

.. automodule:: executor
  :no-undoc-members:

See this :doc:`example<overview>` for usage.

See the Executor APIs for optional arguments.

.. toctree::
   :maxdepth: 1
   :caption: Alternative Executors:

   mpi_executor
   balsam_executor

Executor Class
---------------

Only create an object of this class for running local serial-launched applications.
To run MPI applications and use detected resources, use an alternative Executor
class, as shown above.

.. autoclass:: Executor
  :members: __init__, register_app, submit

.. _task_tag:

Task Class
----------

Tasks are created and returned through the Executor ``submit()`` function. Tasks
can be polled and killed with the respective poll and kill functions. Task
information can be queried through the task attributes below and the query
functions. Note that the task attributes are updated only when they are
polled/killed (or through other task or Executor functions).

.. autoclass:: Task
  :members:
  :exclude-members: calc_task_timing,check_poll
..  :member-order: bysource
..  :members: poll, kill, workdir_exists, file_exists_in_workdir,
              read_file_in_workdir, stdout_exists, read_stdout, stderr_exists, read_stderr

Task Attributes
---------------

Following is a list of task status and configuration attributes that can be
retrieved from a task.

.. note:: These should not be set directly. Tasks are launched by the Executor,
    and task information can be queried through the task attributes
    below and the query functions.

Task status attributes include the following:

:task.state: (string) The task status. One of
             ('UNKNOWN'|'CREATED'|'WAITING'|'RUNNING'|'FINISHED'|'USER_KILLED'|'FAILED')

:task.process: (process obj) The process object used by the underlying process
               manager (e.g., return value of subprocess.Popen).
:task.errcode: (int) The errorcode/return code used by the underlying process manager.
:task.finished: (Boolean) True means task has finished running - not whether it was successful.
:task.success: (Boolean) Did task complete successfully (e.g., the returncode is zero)?
:task.runtime: (int) Time in seconds that task has been running.
:task.total_time: (int) Total time from task submission to completion (only available when task is finished).

Run configuration attributes - some will be autogenerated:

:task.workdir: (string) Work directory for the task
:task.name: (string) Name of task - autogenerated
:task.app: (app obj) Use application/executable, registered using exctr.register_app
:task.app_args: (string) Application arguments as a string
:task.stdout: (string) Name of file where the standard output of the task is written (in task.workdir)
:task.stderr: (string) Name of file where the standard error of the task is written (in task.workdir)
