Debian Codegraph @

pypy3.10/doc/process-objects.html

raw
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> &nbsp; &nbsp; &nbsp; &nbsp; <a class="reference" href="processing-ref.html">Up</a> &nbsp; &nbsp; &nbsp; &nbsp; <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 &gt;&gt;&gt; import processing, time, signal
151 &gt;&gt;&gt; p = processing.Process(target=time.sleep, args=(1000,))
152 &gt;&gt;&gt; print p, p.isAlive()
153 &lt;Process(Process-1, initial)&gt; False
154 &gt;&gt;&gt; p.start()
155 &gt;&gt;&gt; print p, p.isAlive()
156 &lt;Process(Process-1, started)&gt; True
157 &gt;&gt;&gt; p.terminate()
158 &gt;&gt;&gt; print p, p.isAlive()
159 &lt;Process(Process-1, stopped[SIGTERM])&gt; False
160 &gt;&gt;&gt; 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> &nbsp; &nbsp; &nbsp; &nbsp; <a class="reference" href="processing-ref.html">Up</a> &nbsp; &nbsp; &nbsp; &nbsp; <a class="reference" href="queue-objects.html">Next</a>
168 </div>
169 </body>
170 </html>