.. include:: ../global.rst

.. idio:currentmodule:: job-control

job-control structures
----------------------


.. _`job-control/%idio-job`:

.. idio:struct:: %idio-job

   :field: pipeline
   :field: procs
   :field: pgid
   :field: notify-stopped
   :field: notify-completed
   :field: raise?
   :field: raised
   :field: tcattrs
   :field: stdin
   :field: stdout
   :field: stderr
   :field: report-timing
   :field: timing-start
   :field: timing-end
   :field: async
   :field: set-exit-status
   :canonical: job-control/%idio-job

   * `pipeline` is a list of the original commands in the pipeline
   
   * `procs` is a list of the :ref:`%idio-process
     <job-control/%idio-process>` structures, one per element of
     `pipeline`
   
   * `pgid` is the Process Group ID of the pipeline
   
   * `notify-stopped` is a flag to say whether the job being stopped has
     been reported
   
   * `notify-completed` is a flag to say whether any failure on job
     completion has been reported
   
     Notably, this is disabled in logical expressions.
   
   * `raise?` is a flag to say whether any failure on job completion
     should have an ``^rt-command-status-error`` /
     ``^rt-async-command-status-error`` condition raised
   
     Notably, this is disabled in logical expressions thus allowing
     external commands that fail to be used.
   
   * `raised` is a flag to say whether any failure on job completion
     has had a condition raised
   
   * `tcattrs` is a :ref:`struct-termios <libc/struct-termios>`
   
   * `stdin` indicates the overall job *stdin*
   
   * `stdout` indicates the overall job *stdout*
   
   * `stderr` indicates the overall job *stderr*
   
   * `report-timing` is a flag to indicate that a timing report should be
     generated on job completion
   
   * `timing-start` is a list of
   
     #. :ref:`struct-timeval <libc/struct-timeval>`
   
     #. :ref:`struct-rusage <libc/struct-rusage>` for ``libc/RUSAGE_SELF``
   
     #. :ref:`struct-rusage <libc/struct-rusage>` for ``libc/RUSAGE_CHILDREN``
   
   * `timing-end` will be a list of
   
     #. :ref:`struct-timeval <libc/struct-timeval>`
   
     #. :ref:`struct-rusage <libc/struct-rusage>` for ``libc/RUSAGE_SELF``
   
     #. :ref:`struct-rusage <libc/struct-rusage>` for ``libc/RUSAGE_CHILDREN``
   
   * `async` is a flag indicating the job is asynchronous and normally
     set for *Process Substitution* jobs
   
   * `set-exit-status` is a flag indicating whether the job should update
     the pending :lname:`Idio` exit status
   

.. _`job-control/%idio-job?`:

.. idio:function:: job-control/%idio-job? o


   Is `o` an :ref:`%idio-job <job-control/%idio-job>`?
   
   :param o: value to test
   :return: boolean
   

.. _`job-control/make-%idio-job`:

.. idio:function:: job-control/make-%idio-job ...


   create an :ref:`%idio-job <job-control/%idio-job>` from `...`
   
   :param ...: values for `%idio-job`
   :return: `%idio-job`
   :rtype: struct-instance
   

.. _`job-control/%idio-process`:

.. idio:struct:: %idio-process

   :field: argv
   :field: exec
   :field: pid
   :field: completed
   :field: stopped
   :field: status
   :canonical: job-control/%idio-process

   * `argv` is a list of the original arguments in the process
   
   * `exec` is unused
   
   * `pid` is the Process ID of the process
   
   * `completed` is a flag indicating if the process has completed
   
   * `stopped` is a flag indicating if the process has been stopped (with
     ``SIGSTOP``)
   
   * `status` if set, is a C/pointer to the process status as returned by
     :ref:`waitpid <libc/waitpid>`
   
   

.. _`job-control/%idio-process?`:

.. idio:function:: job-control/%idio-process? o


   Is `o` an :ref:`%idio-process <job-control/%idio-process>`?
   
   :param o: value to test
   :return: boolean
   

.. _`job-control/make-%idio-process`:

.. idio:function:: job-control/make-%idio-process ...


   create an :ref:`%idio-process <job-control/%idio-process>` from `...`
   
   :param ...: values for `%idio-process`
   :return: `%idio-process`
   :rtype: struct-instance
   

.. _`job-control/%process-substitution-job`:

.. idio:struct:: %process-substitution-job

   :field: read
   :field: fd
   :field: path
   :field: dir
   :field: suppress
   :canonical: job-control/%process-substitution-job


.. _`job-control/%process-substitution-job?`:

.. idio:function:: job-control/%process-substitution-job? o


   Is `o` an :ref:`%process-substitution-job <job-control/%process-substitution-job>`?
   
   :param o: value to test
   :return: boolean
   

.. _`job-control/make-%process-substitution-job`:

.. idio:function:: job-control/make-%process-substitution-job ...


   create an :ref:`%process-substitution-job <job-control/%process-substitution-job>` from `...`
   
   :param ...: values for `%process-substitution-job`
   :return: `%process-substitution-job`
   :rtype: struct-instance
   

.. _`job-control/add-process-substitution-job`:

.. idio:function:: job-control/add-process-substitution-job job psj


   
   Update the set of process substitution jobs with new job `job`.
   
   :param job: new job
   :type job: an instance of :ref:`%idio-job <job-control/%idio-job>`
   :param job: process substituion details
   :type job: an instance of :ref:`%process-substitution-job <job-control/%process-substitution-job>`
   


.. _`job-control/tidy-process-substitution-job`:

.. idio:function:: job-control/tidy-process-substitution-job job


   
   Update the set of process substitution jobs on the completion of job `job`
   
   :param job: completed job
   :type job: an instance of :ref:`%idio-job <job-control/%idio-job>`
   
   This may involve active closing of file descriptors and/or removal of
   entries in the file system.
   




.. include:: ../commit.rst