******************************************
Control Agent that is Selected to Run Task
******************************************

Problem
=======

You want your task to run only on a specified list of machines.



Solution
========

Use task preconditions to control how a task is assigned. Many options can be controlled, including agent hostname, number of available cores,
and hard disk space.
Use the :py:attr:`task_preconditions <agiparallel.client.Job.task_preconditions>` method to add task preconditions to a job.
The :py:class:`CommonResources <agiparallel.constants.CommonResources>` enumeration contains the most frequently used
resource types.


.. literalinclude:: ..\..\..\code\HowTos\ControlAgent.py
	:language: python
	:linenos:



Discussion
==========

It is a common pattern to execute tasks only on a restricted set of machines. Examples include:

* Forcing the task to be executed only on a predefined set of machines.
* Reserving system resources on a machine; for example: only use 2 cores of a 4 core machine.
* Executing a task only if it has a specific resource, for example: only use machines that have STK installed.
* Executing a task only if it has enough memory or hard disk space.

A helpful method to use in combination with :py:attr:`task_preconditions <agiparallel.client.Job.task_preconditions>` is the
:py:meth:`get_coordinator_snapshot() <agiparallel.client.ClusterJobScheduler.get_coordinator_snapshot>`.
get_coordinator_snapshot will return a list of agents, which can be used to determine currently available resources before tasks are submitted.


See Also
========

Reference
"""""""""
* :py:attr:`task_preconditions <agiparallel.client.Job.task_preconditions>`
* :py:meth:`get_coordinator_snapshot() <agiparallel.client.ClusterJobScheduler.get_coordinator_snapshot>`
* :py:class:`CommonResources <agiparallel.constants.CommonResources>`
* :py:class:`Operator <agiparallel.constants.Operator>`

Other Resources
"""""""""""""""
* :ref:`Get the State of the Cluster`