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

        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.

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