************************
Optimize Task Setup Time
************************

Problem
=======

You want to optimize the amount of time used to call an expensive setup method for a group of tasks.



Solution
========

Create a user defined task environment and place the common setup logic inside the 
:py:meth:`setup() <agiparallel.infrastructure.TaskEnvironment.TaskEnvironment.setup>` method. Set the
:py:class:`TaskEnvironment <agiparallel.infrastructure.TaskEnvironment.TaskEnvironment>` with the job's
:py:attr:`set_task_environment <agiparallel.client.Job.set_task_environment>`.


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



Discussion
==========

For a thorough treatment of the Task Environment concept, read the section :ref:`Task Environment`.

Having common code run before and after one or more tasks can be useful for grouping methods that only need 
to run once before a task. A task environment, much like a task, is a user defined class that gets 
serialized and called in the host. When a host starts a job, the task environment's 
:py:meth:`setup() <agiparallel.infrastructure.TaskEnvironment.TaskEnvironment.setup>` method is called once before any
tasks are executed. When the host gets recycled, the task environment's
:py:meth:`teardown() <agiparallel.infrastructure.TaskEnvironment.TaskEnvironment.teardown>` method is called before the
process exits.

The task environment can be reused for multiple jobs. If the task environment's identification is the same,
the :py:meth:`setup() <agiparallel.infrastructure.TaskEnvironment.TaskEnvironment.setup>` will only be called once. Read more about task environment idenfification :ref:`here <Identification>`.


.. note::
	A common trap during development dealing with task environments happens often enough that it deserves 
	special attention. Because the assemblies in a task environment are not reloaded in the host process, 
	changes to task environment assemblies with the same
	identification will not take effect during the lifetime of the host process. In other words, 
	the host process caches
	the task environment and any changes made to the assemblies in the task environment will not be 
	visible until the host process recycles. There are two workarounds for this issue:

	* Create a new identification every time the assemblies are changed.
	* Restart the coordinator every time the assemblies are changed.


See Also
========

Reference
"""""""""
* :py:attr:`set_task_environment <agiparallel.client.Job.set_task_environment>`

Other Resources
"""""""""""""""
* :ref:`Key Concepts: Task Environment <Task Environment>`
* :ref:`Key Concepts: Task Environment Identification <Identification>`