← Back to branch summary

~ubuntu-branches/ubuntu/maverick/python3.1/maverick

« back to all changes in this revision

Viewing changes to Doc/library/signal.rst

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2009-03-23 00:01:27 UTC
  • Revision ID: james.westby@ubuntu.com-20090323000127-5fstfxju4ufrhthq
Tags: upstream-3.1~a1+20090322
Import upstream version 3.1~a1+20090322

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
 
56
   the default function for the signal.  For example, on most systems the
 
57
   default action for :const:`SIGQUIT` is to dump core and exit, while the
 
58
   default action for :const:`SIGCHLD` 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
 
 
164
.. function:: getitimer(which)
 
165
 
 
166
   Returns current value of a given interval timer specified by *which*.
 
167
 
 
168
 
 
169
.. function:: set_wakeup_fd(fd)
 
170
 
 
171
   Set the wakeup fd to *fd*.  When a signal is received, a ``'\0'`` byte is
 
172
   written to the fd.  This can be used by a library to wakeup a poll or select
 
173
   call, allowing the signal to be fully processed.
 
174
 
 
175
   The old wakeup fd is returned.  *fd* must be non-blocking.  It is up to the
 
176
   library to remove any bytes before calling poll or select again.
 
177
 
 
178
   When threads are enabled, this function can only be called from the main thread;
 
179
   attempting to call it from other threads will cause a :exc:`ValueError`
 
180
   exception to be raised.
 
181
 
 
182
 
 
183
.. function:: siginterrupt(signalnum, flag)
 
184
 
 
185
   Change system call restart behaviour: if *flag* is :const:`False`, system calls
 
186
   will be restarted when interrupted by signal *signalnum*, otherwise system calls will
 
187
   be interrupted. Returns nothing. Availability: Unix (see the man page
 
188
   :manpage:`siginterrupt(3)` for further information).
 
189
 
 
190
   Note that installing a signal handler with :func:`signal` will reset the restart
 
191
   behaviour to interruptible by implicitly calling :cfunc:`siginterrupt` with a true *flag*
 
192
   value for the given signal.
 
193
 
 
194
 
 
195
.. function:: signal(signalnum, handler)
 
196
 
 
197
   Set the handler for signal *signalnum* to the function *handler*.  *handler* can
 
198
   be a callable Python object taking two arguments (see below), or one of the
 
199
   special values :const:`signal.SIG_IGN` or :const:`signal.SIG_DFL`.  The previous
 
200
   signal handler will be returned (see the description of :func:`getsignal`
 
201
   above).  (See the Unix man page :manpage:`signal(2)`.)
 
202
 
 
203
   When threads are enabled, this function can only be called from the main thread;
 
204
   attempting to call it from other threads will cause a :exc:`ValueError`
 
205
   exception to be raised.
 
206
 
 
207
   The *handler* is called with two arguments: the signal number and the current
 
208
   stack frame (``None`` or a frame object; for a description of frame objects, see
 
209
   the reference manual section on the standard type hierarchy or see the attribute
 
210
   descriptions in the :mod:`inspect` module).
 
211
 
 
212
 
 
213
.. _signal-example:
 
214
 
 
215
Example
 
216
-------
 
217
 
 
218
Here is a minimal example program. It uses the :func:`alarm` function to limit
 
219
the time spent waiting to open a file; this is useful if the file is for a
 
220
serial device that may not be turned on, which would normally cause the
 
221
:func:`os.open` to hang indefinitely.  The solution is to set a 5-second alarm
 
222
before opening the file; if the operation takes too long, the alarm signal will
 
223
be sent, and the handler raises an exception. ::
 
224
 
 
225
   import signal, os
 
226
 
 
227
   def handler(signum, frame):
 
228
       print('Signal handler called with signal', signum)
 
229
       raise IOError("Couldn't open device!")
 
230
 
 
231
   # Set the signal handler and a 5-second alarm
 
232
   signal.signal(signal.SIGALRM, handler)
 
233
   signal.alarm(5)
 
234
 
 
235
   # This open() may hang indefinitely
 
236
   fd = os.open('/dev/ttyS0', os.O_RDWR)
 
237
 
 
238
   signal.alarm(0)          # Disable the alarm
 
239