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