| 1 |
<?xml version="1.0" encoding="utf-8" ?> |
| 2 |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| 3 |
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| 4 |
<head> |
| 5 |
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
| 6 |
<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" /> |
| 7 |
<title>Process objects</title> |
| 8 |
<link rel="stylesheet" href="html4css1.css" type="text/css" /> |
| 9 |
</head> |
| 10 |
<body> |
| 11 |
<div class="header"> |
| 12 |
<a class="reference" href="processing-ref.html">Prev</a> <a class="reference" href="processing-ref.html">Up</a> <a class="reference" href="queue-objects.html">Next</a> |
| 13 |
<hr class="header"/> |
| 14 |
</div> |
| 15 |
<div class="document" id="process-objects"> |
| 16 |
<h1 class="title">Process objects</h1> |
| 17 |
<p>Process objects represent activity that is run in a separate process.</p> |
| 18 |
<div class="section"> |
| 19 |
<h1><a id="process" name="process">Process</a></h1> |
| 20 |
<p>The <tt class="docutils literal"><span class="pre">Process</span></tt> class has equivalents of all the methods of |
| 21 |
<tt class="docutils literal"><span class="pre">threading.Thread</span></tt>:</p> |
| 22 |
<blockquote> |
| 23 |
<dl class="docutils"> |
| 24 |
<dt><tt class="docutils literal"><span class="pre">__init__(group=None,</span> <span class="pre">target=None,</span> <span class="pre">name=None,</span> <span class="pre">args=(),</span> <span class="pre">kwargs={})</span></tt></dt> |
| 25 |
<dd><p class="first">This constructor should always be called with keyword |
| 26 |
arguments. Arguments are:</p> |
| 27 |
<dl class="docutils"> |
| 28 |
<dt><tt class="docutils literal"><span class="pre">group</span></tt></dt> |
| 29 |
<dd>should be <tt class="docutils literal"><span class="pre">None</span></tt>; exists for compatibility with |
| 30 |
<tt class="docutils literal"><span class="pre">threading.Thread</span></tt>.</dd> |
| 31 |
<dt><tt class="docutils literal"><span class="pre">target</span></tt></dt> |
| 32 |
<dd>is the callable object to be invoked by the <tt class="docutils literal"><span class="pre">run()</span></tt> |
| 33 |
method. Defaults to None, meaning nothing is called.</dd> |
| 34 |
<dt><tt class="docutils literal"><span class="pre">name</span></tt></dt> |
| 35 |
<dd>is the process name. By default, a unique name is |
| 36 |
constructed of the form |
| 37 |
'Process-N<sub>1</sub>:N<sub>2</sub>:...:N<sub>k</sub>' |
| 38 |
where |
| 39 |
N<sub>1</sub>,N<sub>2</sub>,...,N<sub>k</sub> |
| 40 |
is a sequence of integers whose length is determined by |
| 41 |
the <em>generation</em> of the process.</dd> |
| 42 |
<dt><tt class="docutils literal"><span class="pre">args</span></tt></dt> |
| 43 |
<dd>is the argument tuple for the target invocation. |
| 44 |
Defaults to <tt class="docutils literal"><span class="pre">()</span></tt>.</dd> |
| 45 |
<dt><tt class="docutils literal"><span class="pre">kwargs</span></tt></dt> |
| 46 |
<dd>is a dictionary of keyword arguments for the target |
| 47 |
invocation. Defaults to <tt class="docutils literal"><span class="pre">{}</span></tt>.</dd> |
| 48 |
</dl> |
| 49 |
<p class="last">If a subclass overrides the constructor, it must make sure it |
| 50 |
invokes the base class constructor (<tt class="docutils literal"><span class="pre">Process.__init__()</span></tt>) |
| 51 |
before doing anything else to the process.</p> |
| 52 |
</dd> |
| 53 |
<dt><tt class="docutils literal"><span class="pre">run()</span></tt></dt> |
| 54 |
<dd><p class="first">Method representing the process's activity.</p> |
| 55 |
<p class="last">You may override this method in a subclass. The standard |
| 56 |
<tt class="docutils literal"><span class="pre">run()</span></tt> method invokes the callable object passed to the |
| 57 |
object's constructor as the target argument, if any, with |
| 58 |
sequential and keyword arguments taken from the <tt class="docutils literal"><span class="pre">args</span></tt> and |
| 59 |
<tt class="docutils literal"><span class="pre">kwargs</span></tt> arguments, respectively.</p> |
| 60 |
</dd> |
| 61 |
<dt><tt class="docutils literal"><span class="pre">start()</span></tt></dt> |
| 62 |
<dd><p class="first">Start the process's activity.</p> |
| 63 |
<p class="last">This must be called at most once per process object. It |
| 64 |
arranges for the object's <tt class="docutils literal"><span class="pre">run()</span></tt> method to be invoked in a |
| 65 |
separate process.</p> |
| 66 |
</dd> |
| 67 |
<dt><tt class="docutils literal"><span class="pre">join(timeout=None)</span></tt></dt> |
| 68 |
<dd><p class="first">This blocks the calling thread until the process whose |
| 69 |
<tt class="docutils literal"><span class="pre">join()</span></tt> method is called terminates or until the optional |
| 70 |
timeout occurs.</p> |
| 71 |
<p>If <tt class="docutils literal"><span class="pre">timeout</span></tt> is <tt class="docutils literal"><span class="pre">None</span></tt> then there is no timeout.</p> |
| 72 |
<p>A process can be joined many times.</p> |
| 73 |
<p>A process cannot join itself because this would cause a |
| 74 |
deadlock.</p> |
| 75 |
<p class="last">It is an error to attempt to join a process before it has |
| 76 |
been started.</p> |
| 77 |
</dd> |
| 78 |
<dt><tt class="docutils literal"><span class="pre">getName()</span></tt></dt> |
| 79 |
<dd>Return the process's name.</dd> |
| 80 |
<dt><tt class="docutils literal"><span class="pre">setName(name)</span></tt></dt> |
| 81 |
<dd><p class="first">Set the process's name.</p> |
| 82 |
<p class="last">The name is a string used for identification purposes only. |
| 83 |
It has no semantics. Multiple processes may be given the same |
| 84 |
name. The initial name is set by the constructor.</p> |
| 85 |
</dd> |
| 86 |
<dt><tt class="docutils literal"><span class="pre">isAlive()</span></tt></dt> |
| 87 |
<dd><p class="first">Return whether the process is alive.</p> |
| 88 |
<p class="last">Roughly, a process object is alive from the moment the <tt class="docutils literal"><span class="pre">start()</span></tt> |
| 89 |
method returns until the child process terminates.</p> |
| 90 |
</dd> |
| 91 |
<dt><tt class="docutils literal"><span class="pre">isDaemon()</span></tt></dt> |
| 92 |
<dd>Return the process's daemon flag.</dd> |
| 93 |
<dt><tt class="docutils literal"><span class="pre">setDaemon(daemonic)</span></tt></dt> |
| 94 |
<dd><p class="first">Set the process's daemon flag to the Boolean value |
| 95 |
<tt class="docutils literal"><span class="pre">daemonic</span></tt>. This must be called before <tt class="docutils literal"><span class="pre">start()</span></tt> is called.</p> |
| 96 |
<p>The initial value is inherited from the creating process.</p> |
| 97 |
<p class="last">When a parent process finishes it attempts to stop all of its |
| 98 |
daemonic child processes and then tries to join each of its |
| 99 |
non-daemonic child processes.</p> |
| 100 |
</dd> |
| 101 |
</dl> |
| 102 |
</blockquote> |
| 103 |
<p>In addition process objects also support the following methods.</p> |
| 104 |
<blockquote> |
| 105 |
<dl class="docutils"> |
| 106 |
<dt><tt class="docutils literal"><span class="pre">getPid()</span></tt></dt> |
| 107 |
<dd>Return the process ID. Before the process is spawned this |
| 108 |
will be <tt class="docutils literal"><span class="pre">None</span></tt>.</dd> |
| 109 |
<dt><tt class="docutils literal"><span class="pre">getExitCode()</span></tt></dt> |
| 110 |
<dd>Return the child's exit code. This will be <tt class="docutils literal"><span class="pre">None</span></tt> if the |
| 111 |
process has not yet terminated. A negative value <em>-N</em> |
| 112 |
indicates that the child was terminated by signal <em>N</em>.</dd> |
| 113 |
<dt><tt class="docutils literal"><span class="pre">getAuthKey()</span></tt></dt> |
| 114 |
<dd><p class="first">Return the process's authentication key (a string).</p> |
| 115 |
<p>When the <tt class="docutils literal"><span class="pre">processing</span></tt> package is initialized the main process |
| 116 |
is assigned a random hexadecimal string.</p> |
| 117 |
<p>When a <tt class="docutils literal"><span class="pre">Process</span></tt> object is created it will inherit the |
| 118 |
authentication key of its parent process, although this may be |
| 119 |
changed using <tt class="docutils literal"><span class="pre">setAuthKey()</span></tt> below.</p> |
| 120 |
<p class="last">See <a class="reference" href="connection-ref.html#authentication-keys">Authentication Keys</a>.</p> |
| 121 |
</dd> |
| 122 |
<dt><tt class="docutils literal"><span class="pre">setAuthKey(authkey)</span></tt></dt> |
| 123 |
<dd>Set the process's authentication key which must be a string.</dd> |
| 124 |
<dt><tt class="docutils literal"><span class="pre">terminate()</span></tt></dt> |
| 125 |
<dd><p class="first">Terminate the process. On Unix this is done using the |
| 126 |
<tt class="docutils literal"><span class="pre">SIGTERM</span></tt> signal and on Windows <tt class="docutils literal"><span class="pre">TerminateProcess()</span></tt> is used. |
| 127 |
Note that exit handlers and finally clauses etc will not be |
| 128 |
executed. Also note that descendants of the process will |
| 129 |
<em>not</em> be terminates.</p> |
| 130 |
<div class="last warning"> |
| 131 |
<p class="first admonition-title">Warning</p> |
| 132 |
<p class="last">If this method is used when the associated process is |
| 133 |
using a pipe or queue then the pipe or queue is liable to |
| 134 |
become corrupted and may become unusable by other process. |
| 135 |
Similarly, if the process has acquired a lock or semaphore |
| 136 |
etc. then terminating it is liable to cause other |
| 137 |
processes to deadlock.</p> |
| 138 |
</div> |
| 139 |
</dd> |
| 140 |
</dl> |
| 141 |
</blockquote> |
| 142 |
<p>Note that the <tt class="docutils literal"><span class="pre">start()</span></tt>, <tt class="docutils literal"><span class="pre">join()</span></tt>, <tt class="docutils literal"><span class="pre">isAlive()</span></tt> and <tt class="docutils literal"><span class="pre">getExitCode()</span></tt> |
| 143 |
methods should only be called by the process that created the process |
| 144 |
object.</p> |
| 145 |
</div> |
| 146 |
<div class="section"> |
| 147 |
<h1><a id="example" name="example">Example</a></h1> |
| 148 |
<p>Example usage of some of the methods of <tt class="docutils literal"><span class="pre">Process</span></tt>:</p> |
| 149 |
<pre class="literal-block"> |
| 150 |
>>> import processing, time, signal |
| 151 |
>>> p = processing.Process(target=time.sleep, args=(1000,)) |
| 152 |
>>> print p, p.isAlive() |
| 153 |
<Process(Process-1, initial)> False |
| 154 |
>>> p.start() |
| 155 |
>>> print p, p.isAlive() |
| 156 |
<Process(Process-1, started)> True |
| 157 |
>>> p.terminate() |
| 158 |
>>> print p, p.isAlive() |
| 159 |
<Process(Process-1, stopped[SIGTERM])> False |
| 160 |
>>> p.getExitCode() == -signal.SIGTERM |
| 161 |
True |
| 162 |
</pre> |
| 163 |
</div> |
| 164 |
</div> |
| 165 |
<div class="footer"> |
| 166 |
<hr class="footer" /> |
| 167 |
<a class="reference" href="processing-ref.html">Prev</a> <a class="reference" href="processing-ref.html">Up</a> <a class="reference" href="queue-objects.html">Next</a> |
| 168 |
</div> |
| 169 |
</body> |
| 170 |
</html> |