← Back to branch summary

~malept/ubuntu/lucid/python2.6/dev-dependency-fix

« back to all changes in this revision

Viewing changes to Doc/library/signal.rst

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2009-02-13 12:51:00 UTC
  • Revision ID: james.westby@ubuntu.com-20090213125100-uufgcb9yeqzujpqw
Tags: upstream-2.6.1
Import upstream version 2.6.1

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/library/signal.rst
 
1
 
 
2
:mod:`signal` --- Set handlers for asynchronous events
 
3
======================================================
 
4
 
 
5
.. module:: signal
 
6
   :synopsis: Set handlers for asynchronous events.
 
7
 
 
8
 
 
9
This module provides mechanisms to use signal handlers in Python. Some general
 
10
rules for working with signals and their handlers:
 
11
 
 
12
* A handler for a particular signal, once set, remains installed until it is
 
13
  explicitly reset (Python emulates the BSD style interface regardless of the
 
14
  underlying implementation), with the exception of the handler for
 
15
  :const:`SIGCHLD`, which follows the underlying implementation.
 
16
 
 
17
* There is no way to "block" signals temporarily from critical sections (since
 
18
  this is not supported by all Unix flavors).
 
19
 
 
20
* Although Python signal handlers are called asynchronously as far as the Python
 
21
  user is concerned, they can only occur between the "atomic" instructions of the
 
22
  Python interpreter.  This means that signals arriving during long calculations
 
23
  implemented purely in C (such as regular expression matches on large bodies of
 
24
  text) may be delayed for an arbitrary amount of time.
 
25
 
 
26
* When a signal arrives during an I/O operation, it is possible that the I/O
 
27
  operation raises an exception after the signal handler returns. This is
 
28
  dependent on the underlying Unix system's semantics regarding interrupted system
 
29
  calls.
 
30
 
 
31
* Because the C signal handler always returns, it makes little sense to catch
 
32
  synchronous errors like :const:`SIGFPE` or :const:`SIGSEGV`.
 
33
 
 
34
* Python installs a small number of signal handlers by default: :const:`SIGPIPE`
 
35
  is ignored (so write errors on pipes and sockets can be reported as ordinary
 
36
  Python exceptions) and :const:`SIGINT` is translated into a
 
37
  :exc:`KeyboardInterrupt` exception.  All of these can be overridden.
 
38
 
 
39
* Some care must be taken if both signals and threads are used in the same
 
40
  program.  The fundamental thing to remember in using signals and threads
 
41
  simultaneously is: always perform :func:`signal` operations in the main thread
 
42
  of execution.  Any thread can perform an :func:`alarm`, :func:`getsignal`, 
 
43
  :func:`pause`, :func:`setitimer` or :func:`getitimer`; only the main thread 
 
44
  can set a new signal handler, and the main thread will be the only one to 
 
45
  receive signals (this is enforced by the Python :mod:`signal` module, even 
 
46
  if the underlying thread implementation supports sending signals to 
 
47
  individual threads).  This means that signals can't be used as a means of 
 
48
  inter-thread communication.  Use locks instead.
 
49
 
 
50
The variables defined in the :mod:`signal` module are:
 
51
 
 
52
 
 
53
.. data:: SIG_DFL
 
54
 
 
55
   This is one of two standard signal handling options; it will simply perform the
 
56
   default function for the signal.  For example, on most systems the default
 
57
   action for :const:`SIGQUIT` is to dump core and exit, while the default action
 
58
   for :const:`SIGCLD` is to simply ignore it.
 
59
 
 
60
 
 
61
.. data:: SIG_IGN
 
62
 
 
63
   This is another standard signal handler, which will simply ignore the given
 
64
   signal.
 
65
 
 
66
 
 
67
.. data:: SIG*
 
68
 
 
69
   All the signal numbers are defined symbolically.  For example, the hangup signal
 
70
   is defined as :const:`signal.SIGHUP`; the variable names are identical to the
 
71
   names used in C programs, as found in ``<signal.h>``. The Unix man page for
 
72
   ':cfunc:`signal`' lists the existing signals (on some systems this is
 
73
   :manpage:`signal(2)`, on others the list is in :manpage:`signal(7)`). Note that
 
74
   not all systems define the same set of signal names; only those names defined by
 
75
   the system are defined by this module.
 
76
 
 
77
 
 
78
.. data:: NSIG
 
79
 
 
80
   One more than the number of the highest signal number.
 
81
 
 
82
 
 
83
.. data:: ITIMER_REAL    
 
84
 
 
85
   Decrements interval timer in real time, and delivers :const:`SIGALRM` upon expiration.
 
86
 
 
87
 
 
88
.. data:: ITIMER_VIRTUAL 
 
89
 
 
90
   Decrements interval timer only when the process is executing, and delivers 
 
91
   SIGVTALRM upon expiration.
 
92
 
 
93
 
 
94
.. data:: ITIMER_PROF
 
95
   
 
96
   Decrements interval timer both when the process executes and when the 
 
97
   system is executing on behalf of the process. Coupled with ITIMER_VIRTUAL, 
 
98
   this timer is usually used to profile the time spent by the application 
 
99
   in user and kernel space. SIGPROF is delivered upon expiration.
 
100
 
 
101
 
 
102
The :mod:`signal` module defines one exception:
 
103
 
 
104
.. exception:: ItimerError
 
105
 
 
106
   Raised to signal an error from the underlying :func:`setitimer` or
 
107
   :func:`getitimer` implementation. Expect this error if an invalid
 
108
   interval timer or a negative time is passed to :func:`setitimer`. 
 
109
   This error is a subtype of :exc:`IOError`.
 
110
 
 
111
 
 
112
The :mod:`signal` module defines the following functions:
 
113
 
 
114
 
 
115
.. function:: alarm(time)
 
116
 
 
117
   If *time* is non-zero, this function requests that a :const:`SIGALRM` signal be
 
118
   sent to the process in *time* seconds. Any previously scheduled alarm is
 
119
   canceled (only one alarm can be scheduled at any time).  The returned value is
 
120
   then the number of seconds before any previously set alarm was to have been
 
121
   delivered. If *time* is zero, no alarm is scheduled, and any scheduled alarm is
 
122
   canceled.  If the return value is zero, no alarm is currently scheduled.  (See
 
123
   the Unix man page :manpage:`alarm(2)`.) Availability: Unix.
 
124
 
 
125
 
 
126
.. function:: getsignal(signalnum)
 
127
 
 
128
   Return the current signal handler for the signal *signalnum*. The returned value
 
129
   may be a callable Python object, or one of the special values
 
130
   :const:`signal.SIG_IGN`, :const:`signal.SIG_DFL` or :const:`None`.  Here,
 
131
   :const:`signal.SIG_IGN` means that the signal was previously ignored,
 
132
   :const:`signal.SIG_DFL` means that the default way of handling the signal was
 
133
   previously in use, and ``None`` means that the previous signal handler was not
 
134
   installed from Python.
 
135
 
 
136
 
 
137
.. function:: pause()
 
138
 
 
139
   Cause the process to sleep until a signal is received; the appropriate handler
 
140
   will then be called.  Returns nothing.  Not on Windows. (See the Unix man page
 
141
   :manpage:`signal(2)`.)
 
142
 
 
143
 
 
144
.. function:: setitimer(which, seconds[, interval])
 
145
 
 
146
   Sets given interval timer (one of :const:`signal.ITIMER_REAL`, 
 
147
   :const:`signal.ITIMER_VIRTUAL` or :const:`signal.ITIMER_PROF`) specified
 
148
   by *which* to fire after *seconds* (float is accepted, different from 
 
149
   :func:`alarm`) and after that every *interval* seconds. The interval
 
150
   timer specified by *which* can be cleared by setting seconds to zero.
 
151
 
 
152
   When an interval timer fires, a signal is sent to the process.
 
153
   The signal sent is dependent on the timer being used; 
 
154
   :const:`signal.ITIMER_REAL` will deliver :const:`SIGALRM`, 
 
155
   :const:`signal.ITIMER_VIRTUAL` sends :const:`SIGVTALRM`,
 
156
   and :const:`signal.ITIMER_PROF` will deliver :const:`SIGPROF`.
 
157
 
 
158
   The old values are returned as a tuple: (delay, interval).
 
159
 
 
160
   Attempting to pass an invalid interval timer will cause a 
 
161
   :exc:`ItimerError`.
 
162
 
 
163
   .. versionadded:: 2.6
 
164
 
 
165
 
 
166
.. function:: getitimer(which)
 
167
 
 
168
   Returns current value of a given interval timer specified by *which*.
 
169
 
 
170
   .. versionadded:: 2.6
 
171
 
 
172
 
 
173
.. function:: set_wakeup_fd(fd)
 
174
 
 
175
   Set the wakeup fd to *fd*.  When a signal is received, a ``'\0'`` byte is
 
176
   written to the fd.  This can be used by a library to wakeup a poll or select
 
177
   call, allowing the signal to be fully processed.
 
178
 
 
179
   The old wakeup fd is returned.  *fd* must be non-blocking.  It is up to the
 
180
   library to remove any bytes before calling poll or select again.
 
181
 
 
182
   When threads are enabled, this function can only be called from the main thread;
 
183
   attempting to call it from other threads will cause a :exc:`ValueError`
 
184
   exception to be raised.
 
185
 
 
186
 
 
187
.. function:: siginterrupt(signalnum, flag)
 
188
 
 
189
   Change system call restart behaviour: if *flag* is :const:`False`, system calls
 
190
   will be restarted when interrupted by signal *signalnum*, otherwise system calls will
 
191
   be interrupted. Returns nothing. Availability: Unix (see the man page
 
192
   :manpage:`siginterrupt(3)` for further information).
 
193
   
 
194
   Note that installing a signal handler with :func:`signal` will reset the restart
 
195
   behaviour to interruptible by implicitly calling :cfunc:`siginterrupt` with a true *flag*
 
196
   value for the given signal.
 
197
 
 
198
   .. versionadded:: 2.6
 
199
 
 
200
 
 
201
.. function:: signal(signalnum, handler)
 
202
 
 
203
   Set the handler for signal *signalnum* to the function *handler*.  *handler* can
 
204
   be a callable Python object taking two arguments (see below), or one of the
 
205
   special values :const:`signal.SIG_IGN` or :const:`signal.SIG_DFL`.  The previous
 
206
   signal handler will be returned (see the description of :func:`getsignal`
 
207
   above).  (See the Unix man page :manpage:`signal(2)`.)
 
208
 
 
209
   When threads are enabled, this function can only be called from the main thread;
 
210
   attempting to call it from other threads will cause a :exc:`ValueError`
 
211
   exception to be raised.
 
212
 
 
213
   The *handler* is called with two arguments: the signal number and the current
 
214
   stack frame (``None`` or a frame object; for a description of frame objects, see
 
215
   the reference manual section on the standard type hierarchy or see the attribute
 
216
   descriptions in the :mod:`inspect` module).
 
217
 
 
218
 
 
219
.. _signal-example:
 
220
 
 
221
Example
 
222
-------
 
223
 
 
224
Here is a minimal example program. It uses the :func:`alarm` function to limit
 
225
the time spent waiting to open a file; this is useful if the file is for a
 
226
serial device that may not be turned on, which would normally cause the
 
227
:func:`os.open` to hang indefinitely.  The solution is to set a 5-second alarm
 
228
before opening the file; if the operation takes too long, the alarm signal will
 
229
be sent, and the handler raises an exception. ::
 
230
 
 
231
   import signal, os
 
232
 
 
233
   def handler(signum, frame):
 
234
       print 'Signal handler called with signal', signum
 
235
       raise IOError, "Couldn't open device!"
 
236
 
 
237
   # Set the signal handler and a 5-second alarm
 
238
   signal.signal(signal.SIGALRM, handler)
 
239
   signal.alarm(5)
 
240
 
 
241
   # This open() may hang indefinitely
 
242
   fd = os.open('/dev/ttyS0', os.O_RDWR)  
 
243
 
 
244
   signal.alarm(0)          # Disable the alarm
 
245