.. include:: header.txt

=================
 Process objects
=================

Process objects represent activity that is run in a separate process.


Process
=======

The `Process` class has equivalents of all the methods of
`threading.Thread`:

    `__init__(group=None, target=None, name=None, args=(), kwargs={})`
        This constructor should always be called with keyword
        arguments. Arguments are: 

        `group`
            should be `None`; exists for compatibility with 
            `threading.Thread`.

        `target` 
            is the callable object to be invoked by the `run()`
            method.  Defaults to None, meaning nothing is called.

        `name` 
            is the process name. By default, a unique name is
            constructed of the form 
            'Process-N\ :sub:`1`:N\ :sub:`2`:...:N\ :sub:`k`' 
            where 
            N\ :sub:`1`,N\ :sub:`2`,...,N\ :sub:`k` 
            is a sequence of integers whose length is determined by
            the *generation* of the process.

        `args` 
            is the argument tuple for the target invocation.
            Defaults to `()`.

        `kwargs` 
            is a dictionary of keyword arguments for the target
            invocation. Defaults to `{}`.

        If a subclass overrides the constructor, it must make sure it
        invokes the base class constructor (`Process.__init__()`)
        before doing anything else to the process.

    `run()`
         Method representing the process's activity.  

         You may override this method in a subclass. The standard
         `run()` method invokes the callable object passed to the
         object's constructor as the target argument, if any, with
         sequential and keyword arguments taken from the `args` and
         `kwargs` arguments, respectively.

    `start()`
        Start the process's activity.  

        This must be called at most once per process object. It
        arranges for the object's `run()` method to be invoked in a
        separate process.

    `join(timeout=None)`
        This blocks the calling thread until the process whose
        `join()` method is called terminates or until the optional
        timeout occurs.

        If `timeout` is `None` then there is no timeout.

        A process can be joined many times. 

        A process cannot join itself because this would cause a
        deadlock.

        It is an error to attempt to join a process before it has 
        been started.

    `getName()`
        Return the process's name.

    `setName(name)` 
        Set the process's name.
        
        The name is a string used for identification purposes only. 
        It has no semantics. Multiple processes may be given the same 
        name. The initial name is set by the constructor.

    `isAlive()`
        Return whether the process is alive. 

        Roughly, a process object is alive from the moment the `start()`
        method returns until the child process terminates.  A paused
        process is considered to be alive.

    `isDaemon()`
        Return the process's daemon flag. 

    `setDaemon(daemonic)`
        Set the process's daemon flag to the Boolean value
        `daemonic`. This must be called before `start()` is called.  

        The initial value is inherited from the creating process.

        When a parent process finishes it attempts to stop all of its
        daemonic child processes and then tries to join each of its
        non-daemonic child processes.

In addition process objects also support the following methods.

    `stop()`
        Causes the `processing.ProcessExit` exception to be raised in
        the child process.  This exception type is a subclass of
        `SystemExit`.

        Note that the child process might catch and ignore the
        exception.

    `getAuthKey()`
        Return the process's authentication key (a string).

        When the `processing` package is initialized the main process
        is assigned a random hexadecimal string.

        When a `Process` object is created it will inherit the
        authentication key of its parent process, although this may be
        changed using `setAuthKey()` below.

        See `Authentication Keys <connection-ref.html#authentication-keys>`_.

    `setAuthKey(authkey)`
        Set the process's authentication key which must be a string.

    `getPid()`
        Return the process ID.  Before the process is spawned this 
        will be `None`.

    `getExitCode()`
        Return the child's exit code.  This will be `None` if the
        process has not yet terminated.  A negative value *-N*
        indicates that the child was terminated by signal *N*.

Note that the `start()`, `join()`, `isAlive()` and `getExitCode()`
methods should only be called by the process that created the process
object.


Example
=======

The `stop()` method can be used to kill a process.  For example on
Unix an instance of `emacs` can be started and then stopped as
follows::

    >>> import os, processing
    >>> p = processing.Process(target=os.execlp, args=['emacs', 'emacs'])
    >>> print p
    <Process(Process-1, initial)>
    >>> p.start()
    >>> print p
    <Process(Process-1, started)>
    >>> p.stop()
    >>> print p
    <Process(Process-1, stopped[ProcessExit])>

.. _Prev: processing-ref.html
.. _Up: processing-ref.html
.. _Next: manager-objects.html
