.. bronx documentation master file, created by
   sphinx-quickstart on Wed Nov  2 14:34:54 2022.
.. :noindex:

Welcome to taylorism's documentation!
=====================================

A framework for parallelisation of tasks.

The package works with three levels of subprocessing:

- the main program, in which are defined each task "instructions",
  and that communicates with the intermediate subprocess
- the intermediate subprocess, that receive instructions sets from the main
  program and distributes them to a range of subprocesses
- the working subprocesses, that are defined by their instructions, execute
  it and then return to the intermediate process.

This segmentation takes the image of a Boss distributing instructions to
Workers, and getting their report when they finish.

The main program can:

- initiate the :class:`~taylorism.Boss` class
- give instructions to the :class:`~taylorism.Boss`, for them to be executed
  (by the :class:`~taylorism.Worker` objects)
- tell the :class:`~taylorism.Boss` to send the :class:`~taylorism.Worker`
  objects to work
- tell the :class:`~taylorism.Boss` to stop the :class:`~taylorism.Worker`
  objects
- inform the :class:`~taylorism.Boss` that there will not be any more
  instruction to do
- wait until all instructions have been executed
- get report (interim or final) from the :class:`~taylorism.Boss` (composed of
  :class:`~taylorism.Worker` objects reports)

The :class:`~taylorism.Boss` (in its subprocess loop):

- receives either series of instructions or "control signals" from the main
  program. Control signals concern:

    - halt/resume execution of instructions
    - request for (interim) report
    - end of instructions information
    - stop signals (letting workers finish current tasks or not)

- collects reports from the workers, with handling of their errors: if an error
  occurs in a subprocess, all other subprocesses are stopped and the error is
  returned to the main program.
- schedule execution of instructions, asking a Scheduler with regards to:

    - pending instructions (work to do)
    - current workers (work being done)
    - previous reports (work already done)

  (cf. :mod:`taylorism.schedulers` doc for more details).

The :class:`~taylorism.Worker` objects are defined BY their instructions (their
attributes), and their task (what they do with their instructions).
Each :class:`~taylorism.Worker` is an independent subprocess, triggered by the
:class:`~taylorism.Boss` subprocess and supposed to return to it the report of
its work when finished.

Use of the module
-----------------

A proper use is to define a custom worker class inheriting from
:class:`~taylorism.Worker`, with all its necessary instructions as footprints
attributes.
Then implement the task to be done in the :py:meth:`~taylorism.Worker._task()`
method.

The so-implemented workers will then be "hired"=generated by the
:class:`~taylorism.Boss` as soon as the instructions given to the
:class:`~taylorism.Boss` meet those of the workers (:mod:`footprints`
magics !).

Cf. :mod:`taylorism.examples` for a simple example.


Dependencies
------------

:mod:`footprints` (MF package)

:mod:`bronx` (MF package)


Package auto-documentation
--------------------------

For more details, please dive in the documentation embedded in sub-modules:

.. autosummary::
   :toctree: _autosummary
   :template: autosummary/custom-module.tpl
   :recursive:

   taylorism


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`