:py:mod:`buildtest.executors.setup`
===================================

.. py:module:: buildtest.executors.setup

.. autoapi-nested-parse::

   This module is responsible for setup of executors defined in buildtest
   configuration. The BuildExecutor class initializes the executors and chooses the
   executor class to call depending on executor name.



Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   buildtest.executors.setup.BuildExecutor




Attributes
~~~~~~~~~~

.. autoapisummary::

   buildtest.executors.setup.logger


.. py:data:: logger

   

.. py:class:: BuildExecutor(site_config, account=None, maxpendtime=None, pollinterval=None, timeout=None, max_jobs=None)


   A BuildExecutor is responsible for initialing executors from buildtest configuration
   file which provides a list of executors. This class keeps track of all executors and provides
   the following methods:

   - **setup**: This method will  write executor's ``before_script.sh``  that is sourced in each test upon calling executor.
   - **run**: Responsible for invoking executor's **run** method based on builder object which is of type BuilderBase.
   - **poll**: This is responsible for invoking ``poll`` method for corresponding executor from the builder object by checking job state

   Initialize executors, meaning that we provide the buildtest
   configuration that are validated, and can instantiate
   each executor to be available.

   :param site_config: instance of SiteConfiguration class that has the buildtest configuration
   :type site_config: buildtest.config.SiteConfiguration
   :param account: pass account name to charge batch jobs.
   :type account: str, optional
   :param maxpendtime: maximum pend time in second until job is cancelled.
   :type maxpendtime: int, optional
   :param pollinterval: Number of seconds to wait until polling batch jobs
   :type pollinterval: int, optional
   :param max_jobs: Maximum number of jobs to run at a time.
   :type max_jobs: int, optional

   .. py:method:: __str__()

      Return str(self).


   .. py:method:: __repr__()

      Return repr(self).


   .. py:method:: names()

      Return a list of executor names


   .. py:method:: get(name)

      Given the name of an executor return the executor object which is of subclass of `BaseExecutor`


   .. py:method:: get_validbuilders()

      Return a list of valid builders that were run


   .. py:method:: _choose_executor(builder)

      Choose executor is called at the onset of a run and poll stage. Given a builder
      object we retrieve the executor property ``builder.executor`` of the builder and check if
      there is an executor object and of type `BaseExecutor`.

      :param builder: An instance object of BuilderBase type
      :type builder: buildtest.buildsystem.base.BuilderBase


   .. py:method:: setup()

      This method creates directory ``var/executors/<executor-name>`` for every executor defined
      in buildtest configuration and write scripts `before_script.sh` if the field ``before_script``
      is specified in executor section. This method is called after executors are initialized in the
      class **__init__** method.


   .. py:method:: select_builders_to_run(builders)

      This method will return list of builders that need to run. We need to check any builders that have a job dependency
      and make sure the dependent jobs are finished prior to running builder. The return method will be a list of builders
      to run.


   .. py:method:: check_state(builder, testnames, name, testname)

      Check the state of the job and set the builder dependency accordingly.


   .. py:method:: check_returncode(builder, testnames, name, testname)

      Check the returncode of the job and set the builder dependency accordingly.


   .. py:method:: run(builders)

      This method is responsible for running the build script for each builder async and
      gather the results. We setup a pool of worker settings by invoking ``multiprocessing.pool.Pool``
      and use `multiprocessing.pool.Pool.apply_sync() <https://docs.python.org/3/library/multiprocessing.html#multiprocessing.pool.Pool.apply_async>`_
      method for running test async which returns
      an object of type `multiprocessing.pool.AsyncResult <https://docs.python.org/3/library/multiprocessing.html#multiprocessing.pool.AsyncResult>`_
      which holds the result. Next we wait for results to arrive using `multiprocessing.pool.AsyncResult.get() <https://docs.python.org/3/library/multiprocessing.html#multiprocessing.pool.AsyncResult.get>`_
      method in a infinite loop until all test results are retrieved. The return type is the same builder object which is added to list
      of valid builders that is returned at end of method.


   .. py:method:: poll(pending_jobs)

      Poll all until all jobs are complete. At each poll interval, we poll each builder
      job state. If job is complete or failed we remove job from pending queue. In each interval we sleep
      and poll jobs until there is no pending jobs.


   .. py:method:: _print_job_details(active_jobs)

      Print pending jobs in table format during each poll step

      :param active_jobs: List of builders whose jobs are pending, suspended or running
      :type active_jobs: list
      :param completed_jobs: List of builders whose jobs are completed
      :type completed_jobs: list


   .. py:method:: _cleanup_when_exception()

      This method is invoked by cleaning up any builders that are when exception is raised