process-objects.html 9.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170
  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>