.. _monitoringjobs:

***************
Monitoring Jobs
***************

The API provides events that are called after key state changes occur in the job scheduler.
Examples include when a task changes state, when a task completes, and when a task reports new progress
in cases where data is progressively returned back to the client during long running jobs.

Overview
========

* :ref:`Responding to task state changes`
	* :ref:`Task Completed`
	* :ref:`Job Completed`
	* :ref:`Task State Changed`
* :ref:`Reporting the progress of tasks`




Responding to Task State Changes
================================

Every time a task changes state, the job scheduler notifies the client with an event. A task's result can be processed immediately upon task completion.


Task Completed
""""""""""""""

The :py:attr:`job.task_completed <agiparallel.client.Job.task_completed>` and 
:py:attr:`task.on_completed` events are raised when a task completes.
Once a task completes, its results can be processed immediately.


.. literalinclude:: .\..\..\code\ProgrammersGuide\TaskCompleted.py
	:language: python
	:linenos:




Job Completed
"""""""""""""

:py:attr:`job.job_completed <agiparallel.client.Job.job_completed>` is raised when all tasks from the job are completed.


.. literalinclude:: .\..\..\code\ProgrammersGuide\JobCompleted.py
	:language: python
	:linenos:




Task State Changed
""""""""""""""""""

:py:obj:`job.task_state_changed <agiparallel.client.Job.task_state_changed>` is raised when a task
changes state. For example, when a task changes its state from :py:obj:`ASSIGNED <agiparallel.constants.TaskStatus.ASSIGNED>` to
:py:obj:`RUNNING <agiparallel.constants.TaskStatus.RUNNING>`.


.. literalinclude:: .\..\..\code\ProgrammersGuide\TaskStateChanged.py
	:language: python
	:linenos:





Reporting the Progress of Tasks
===============================



Task Progress Updated
"""""""""""""""""""""

A task can specify a user defined progress value by calling :py:meth:`set_progress` on the task.
The reported progress values are not used in any way. For example, the progress parameter can range from 20 to 2500.
The job's :py:attr:`task_progress_updated` is called at **200** millisecond intervals
if the progress of the task is updated. If :py:meth:`set_progress` is called multiple times during a single 200 millisecond interval, only a single progress event will be sent.

The reported progress values are also dynamically shown in the monitoring applications. This can be very valuable when monitoring applications.

Below is a common pattern to print the complete progress of the job given the progress of each task:


.. note::
	Notice in this code snippet :py:func:`update_progress` is used to call the update function. This overload to 
	:py:meth:`wait_until_done() <agiparallel.client.Job.wait_until_done>` can be used to unblock from
	:py:meth:`wait_until_done() <agiparallel.client.Job.wait_until_done>` to do something quickly.
	For example, checking a canceling flag is also very common.



.. literalinclude:: .\..\..\code\ProgrammersGuide\TaskProgress.py
	:language: python
	:linenos:



See Also
========

Reference
"""""""""
* :py:meth:`wait_until_done <agiparallel.client.Job.wait_until_done>`