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