.. include:: header.txt

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

Process objects represent activity that is run in a separate 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 if the process has yet to start.  [#]_

        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.

As an 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.


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

.. [#] Unlike `Thread.setName()` this method can only be used before
       `start()` is called.

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

