.. include:: header.txt

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

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

The `Process` class is defined in the `processing.process` module but is also
directly available from `processing`.


Process
=======

The `Process` class is almost a clone of `threading.Thread`.  The
methods are

    `__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.

    `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. [#]_


    `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.

    `join()`
        Wait until the process terminates.  This blocks the calling 
        thread until the process whose `join()` method is called 
        terminates. [#]_
        
        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.

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

        When the `processing` package is initialized the main process
        is assigned a random hexadecimal string produced using
        `os.urandom()`.

        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>`_.
        [5]_

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

        If `value` is `None` then a new key is automatically
        generated. [5]_

.. note::

   Unlike thread objects, process objects do not have methods
   `isAlive()`, `isDaemon()` or `setDaemon()`.


.. [#] The default names of thread objects instead take the form
       'Thread-N' where N is an integer.

.. [#] `start()` calls either `os.fork()` or `os.spawnv()`
       depending on the platform.

.. [#] Unlike `Thread.join()` this method does not support an
       optional timeout argument.

.. [#] Calling the `setName()` method of a process object from one
       process will not effect the name by which that process is known
       to any other started processes.

.. [5] `Thread` objects do not have `getAuthKey()` and `setAuthKey()`
       methods.


Example
=======

The following program prints 'Hello Bob' from a child process::

    from processing import Process

    def f(name):
        print 'Hello', name

    if __name__ == '__main__':
        p = Process(target=f, args=['Bob'])
        p.start()
        p.join()

See `Programming guidelines <programming-guidelines.html>`_ for an
explanation of why the `if __name__ == '__main__':` test is needed
on Windows.

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