.. include:: header.txt

==============================
 processing package reference 
==============================

The `processing` package mostly replicates the API of the `threading`
module.

The following functions and classes which correspond to analogous
to objects from `threading` or `Queue`:

    **class** `Process(group=None, target=None, name=None, args=(), kwargs={})`
        An analogue of `threading.Thread`.

        See `Process objects`_.

    `currentProcess()`
        An analogue of `threading.currentThread`

        Returns the object corresponding to the current process.

    `BoundedSemaphore(value=1)`
        Returns a bounded semaphore object: a clone of
        `threading.BoundedSemaphore`. [1]_

    `Condition(lock=None)`
        Returns a condition variable: a clone of `threading.Condition`.
        
        If `lock` is specified then it should be a `Lock` or `RLock`
        object from `processing`. [1]_
        
    `Event()`
        Returns an event object: a clone of `threading.Event`. [1]_

    `Lock()` 
        Returns a lock object: a clone of `threading.Lock` except
        that acquiring a lock already owned by the calling thread
        raises an exception instead of causing a deadlock). [1]_
                
    `Queue(maxsize=0)`
        Returns a queue object: a clone of `Queue.Queue`.

        This is an alias for either `processing.PosixQueue` (if it is
        available) or `processing.PipeQueue`.  

        Note that a queue created by `Queue.Queue()` will have
        infinite capacity and that putting an object on it will never
        block (or raise a `Full` exception).  This is not true of a
        queue created with `processing.Queue()` so a little extra care
        may be needed to avoid the possibility of deadlocks.

        Note that often it is more convenient to use `Pipe()`
        instead. [1]_
        
    `RLock()`
        Returns a recursive lock object: a clone of `threading.RLock` [1]_
        
    `Semaphore(value=1)`
        Returns a bounded semaphore object: a clone of
        `threading.Semaphore`. [1]_


Objects with no equivalents in the `threading` module are:
     
    `activeChildren()`
        Return list of all live children of the current process.
        
        Calling this has the side affect of "joining" any processes
        which have already finished.
        
    `Pipe()`
        Returns a pair of connection objects representing the ends of
        a duplex connection.  (See `Connection objects
        <connection-ref.html#connection-objects>`_.)  These connection
        objects can be inherited by child processes.

        Note that (unlike a queue object) connection objects are not
        thread/process safe. [1]_
                
    `Manager()`
        Returns a `SyncManager` object which can be used for sharing
        objects between processes.  The returned manager object
        corresponds to a spawned child process and has methods which
        will create shared objects and return corresponding proxies.

        The methods for creating shared objects are

            `list`, `dict`, `Namespace`, `SharedValue`,
            `SharedStruct`, `SharedArray`, `Lock`, `RLock`,
            `Semaphore`, `BoundedSemaphore`, `Condition`, `Event`,
            `Queue`

        See `SyncManager <manager-objects.html#syncmanager>`_ and
        `Proxy objects`_.
        
    `LocalManager()` 
        Returns a manager object with instance methods
        
            `SharedValue`, `SharedStruct`, `SharedArray` 

        for creating objects stored in shared memory map for storing
        data.  Also has static methods
        
            `Lock`, `RLock`, `Semaphore`, `BoundedSemaphore`,
            `Condition`, `Event`, `Queue`

        which are just aliases for the types in the `processing`
        namespace.  See `LocalManager
        <manager-objects.html#shared-memory-managers>`_. [1]_

    `PipeQueue(maxsize=0)`
        Returns a near clone of `Queue.Queue` except that the
        `qsize()` method is not implemented.  It is implemented using
        a pipe and some locks/semaphores.
        
        On unix if a client terminates while it is reading or writing
        from the queue, other clients reading from the queue may lose
        track of where messages boundaries are or may retrieve
        incomplete messages.  At least on Windows a keyboard interrupt
        (SIGINT) or the use of a process's `stop()` method should not
        cause such a problem.
        
        Placing an object on a `PipeQueue` can block because of lack
        of buffer space even if a zero timeout is used. [1]_
        
    `PosixQueue(maxsize=0, msgsize=0)`
        Returns a near clone of `Queue.Queue` implemented using a (Unix
        only) posix message queue.
        
        If `maxsize` is non-zero it determines the maximum number of
        messages that can be in the queue and if `msgsize` is non-zero
        it determines the maximum size in bytes of a message.  If
        either is zero then the system default (which is finite) is
        used.  These defaults can be obtained as a pair of integers by
        calling the `getdefaults()` method.  A typical return value on
        Linux is `(10, 8192)`.

        Note that if `maxsize` or `msgsize` is larger than the system
        maximum then an exception will be thrown.  On Linux the system
        maximums can viewed and modified through the `/proc`
        filesystem --- see `man 7 mq_overview`.

        Requires the `_processing` extension to have posix message
        queue support.
        
    `freezeSupport()`
        Adds support for when a program which uses the `processing`
        package has been frozen to produce a Windows executable.  (Has
        been tested with `py2exe`, `PyInstaller` and `cx_Freeze`.)

        One needs to call this function straight after the `if __name__
        == '__main__'` line of the main module.  For example ::

            from processing import Process, freezeSupport

            def f():
                print "hello world!"

            if __name__ == '__main__':
                freezeSupport()
                p = Process(target=f)
                p.start()

        If the `freezeSupport()` line is missed out then the frozen
        executable produced from this module would (on Windows)
        recursively create new processes.

        If the module is being run normally by the python interpreter
        then `freezeSupport()` has no effect.

    **exception** `ProcessExit`
        Exception raised in another process when the `Process.stop()`
        method is used.  This is a subclass of `SystemExit`.


.. [1]
    These functions require that the `_processing` extension to be
    compiled (with support for semaphores).  Note that `Manager` does
    *not* require `_processing` but supports almost all the same
    functionality.

.. note::
   * The `processing.dummy` package replicates the API of `processing`
     but is no more than a wrapper around the `threading` module.
     
   * `processing` contains no analogues of `activeCount`,
     `enumerate`, `settrace`, `setprofile`, `Timer`, or
     `local` from the `threading` module.


Subsections
-----------

* `Process objects <process-objects.html>`_
* `Manager objects <manager-objects.html>`_
* `Proxy objects <proxy-objects.html>`_
* `connection sub-package <connection-ref.html>`_


.. _Prev: intro.html
.. _Up: index.html
.. _Next: process-objects.html
