process-objects.txt 5.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176
  1. .. include:: header.txt
  2. =================
  3. Process objects
  4. =================
  5. Process objects represent activity that is run in a separate process.
  6. Process
  7. =======
  8. The `Process` class has equivalents of all the methods of
  9. `threading.Thread`:
  10. `__init__(group=None, target=None, name=None, args=(), kwargs={})`
  11. This constructor should always be called with keyword
  12. arguments. Arguments are:
  13. `group`
  14. should be `None`; exists for compatibility with
  15. `threading.Thread`.
  16. `target`
  17. is the callable object to be invoked by the `run()`
  18. method. Defaults to None, meaning nothing is called.
  19. `name`
  20. is the process name. By default, a unique name is
  21. constructed of the form
  22. 'Process-N\ :sub:`1`:N\ :sub:`2`:...:N\ :sub:`k`'
  23. where
  24. N\ :sub:`1`,N\ :sub:`2`,...,N\ :sub:`k`
  25. is a sequence of integers whose length is determined by
  26. the *generation* of the process.
  27. `args`
  28. is the argument tuple for the target invocation.
  29. Defaults to `()`.
  30. `kwargs`
  31. is a dictionary of keyword arguments for the target
  32. invocation. Defaults to `{}`.
  33. If a subclass overrides the constructor, it must make sure it
  34. invokes the base class constructor (`Process.__init__()`)
  35. before doing anything else to the process.
  36. `run()`
  37. Method representing the process's activity.
  38. You may override this method in a subclass. The standard
  39. `run()` method invokes the callable object passed to the
  40. object's constructor as the target argument, if any, with
  41. sequential and keyword arguments taken from the `args` and
  42. `kwargs` arguments, respectively.
  43. `start()`
  44. Start the process's activity.
  45. This must be called at most once per process object. It
  46. arranges for the object's `run()` method to be invoked in a
  47. separate process.
  48. `join(timeout=None)`
  49. This blocks the calling thread until the process whose
  50. `join()` method is called terminates or until the optional
  51. timeout occurs.
  52. If `timeout` is `None` then there is no timeout.
  53. A process can be joined many times.
  54. A process cannot join itself because this would cause a
  55. deadlock.
  56. It is an error to attempt to join a process before it has
  57. been started.
  58. `getName()`
  59. Return the process's name.
  60. `setName(name)`
  61. Set the process's name.
  62. The name is a string used for identification purposes only.
  63. It has no semantics. Multiple processes may be given the same
  64. name. The initial name is set by the constructor.
  65. `isAlive()`
  66. Return whether the process is alive.
  67. Roughly, a process object is alive from the moment the `start()`
  68. method returns until the child process terminates.
  69. `isDaemon()`
  70. Return the process's daemon flag.
  71. `setDaemon(daemonic)`
  72. Set the process's daemon flag to the Boolean value
  73. `daemonic`. This must be called before `start()` is called.
  74. The initial value is inherited from the creating process.
  75. When a parent process finishes it attempts to stop all of its
  76. daemonic child processes and then tries to join each of its
  77. non-daemonic child processes.
  78. In addition process objects also support the following methods.
  79. `getPid()`
  80. Return the process ID. Before the process is spawned this
  81. will be `None`.
  82. `getExitCode()`
  83. Return the child's exit code. This will be `None` if the
  84. process has not yet terminated. A negative value *-N*
  85. indicates that the child was terminated by signal *N*.
  86. `getAuthKey()`
  87. Return the process's authentication key (a string).
  88. When the `processing` package is initialized the main process
  89. is assigned a random hexadecimal string.
  90. When a `Process` object is created it will inherit the
  91. authentication key of its parent process, although this may be
  92. changed using `setAuthKey()` below.
  93. See `Authentication Keys <connection-ref.html#authentication-keys>`_.
  94. `setAuthKey(authkey)`
  95. Set the process's authentication key which must be a string.
  96. `terminate()`
  97. Terminate the process. On Unix this is done using the
  98. `SIGTERM` signal and on Windows `TerminateProcess()` is used.
  99. Note that exit handlers and finally clauses etc will not be
  100. executed. Also note that descendants of the process will
  101. *not* be terminates.
  102. .. warning::
  103. If this method is used when the associated process is
  104. using a pipe or queue then the pipe or queue is liable to
  105. become corrupted and may become unusable by other process.
  106. Similarly, if the process has acquired a lock or semaphore
  107. etc. then terminating it is liable to cause other
  108. processes to deadlock.
  109. Note that the `start()`, `join()`, `isAlive()` and `getExitCode()`
  110. methods should only be called by the process that created the process
  111. object.
  112. Example
  113. =======
  114. Example usage of some of the methods of `Process`::
  115. >>> import processing, time, signal
  116. >>> p = processing.Process(target=time.sleep, args=(1000,))
  117. >>> print p, p.isAlive()
  118. <Process(Process-1, initial)> False
  119. >>> p.start()
  120. >>> print p, p.isAlive()
  121. <Process(Process-1, started)> True
  122. >>> p.terminate()
  123. >>> print p, p.isAlive()
  124. <Process(Process-1, stopped[SIGTERM])> False
  125. >>> p.getExitCode() == -signal.SIGTERM
  126. True
  127. .. _Prev: processing-ref.html
  128. .. _Up: processing-ref.html
  129. .. _Next: queue-objects.html