text: .. 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.
  
      `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.
  
      `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*.
  
      `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.
  
      `terminate()`
          Terminate the process.  On Unix this is done using the
          `SIGTERM` signal and on Windows `TerminateProcess()` is used.
          Note that exit handlers and finally clauses etc will not be
          executed.  Also note that descendants of the process will
          *not* be terminates.
  
          .. warning::
  
              If this method is used when the associated process is
              using a pipe or queue then the pipe or queue is liable to
              become corrupted and may become unusable by other process.
              Similarly, if the process has acquired a lock or semaphore
              etc. then terminating it is liable to cause other
              processes to deadlock.
  
  Note that the `start()`, `join()`, `isAlive()` and `getExitCode()`
  methods should only be called by the process that created the process
  object.
  
  
  Example
  =======
  
  Example usage of some of the methods of `Process`::
  
      >>> import processing, time, signal
      >>> p = processing.Process(target=time.sleep, args=(1000,))
      >>> print p, p.isAlive()
      <Process(Process-1, initial)> False
      >>> p.start()
      >>> print p, p.isAlive()
      <Process(Process-1, started)> True
      >>> p.terminate()
      >>> print p, p.isAlive()
      <Process(Process-1, stopped[SIGTERM])> False
      >>> p.getExitCode() == -signal.SIGTERM
      True
  
  .. _Prev: processing-ref.html
  .. _Up: processing-ref.html
  .. _Next: queue-objects.html
  