File indexing completed on 2024-04-28 15:53:59
0001 #!/usr/bin/env python2.7 0002 # -*- coding: utf-8 -*- 0003 """:synopsis: Set handlers for asynchronous events. 0004 0005 0006 This module provides mechanisms to use signal handlers in Python. Some general 0007 rules for working with signals and their handlers: 0008 0009 * A handler for a particular signal, once set, remains installed until it is 0010 explicitly reset (Python emulates the BSD style interface regardless of the 0011 underlying implementation), with the exception of the handler for 0012 :const:`SIGCHLD`, which follows the underlying implementation. 0013 0014 * There is no way to "block" signals temporarily from critical sections (since 0015 this is not supported by all Unix flavors). 0016 0017 * Although Python signal handlers are called asynchronously as far as the Python 0018 user is concerned, they can only occur between the "atomic" instructions of the 0019 Python interpreter. This means that signals arriving during long calculations 0020 implemented purely in C (such as regular expression matches on large bodies of 0021 text) may be delayed for an arbitrary amount of time. 0022 0023 * When a signal arrives during an I/O operation, it is possible that the I/O 0024 operation raises an exception after the signal handler returns. This is 0025 dependent on the underlying Unix system's semantics regarding interrupted system 0026 calls. 0027 0028 * Because the C signal handler always returns, it makes little sense to catch 0029 synchronous errors like :const:`SIGFPE` or :const:`SIGSEGV`. 0030 0031 * Python installs a small number of signal handlers by default: :const:`SIGPIPE` 0032 is ignored (so write errors on pipes and sockets can be reported as ordinary 0033 Python exceptions) and :const:`SIGINT` is translated into a 0034 :exc:`KeyboardInterrupt` exception. All of these can be overridden. 0035 0036 * Some care must be taken if both signals and threads are used in the same 0037 program. The fundamental thing to remember in using signals and threads 0038 simultaneously is: always perform :func:`signal` operations in the main thread 0039 of execution. Any thread can perform an :func:`alarm`, :func:`getsignal`, 0040 :func:`pause`, :func:`setitimer` or :func:`getitimer`; only the main thread 0041 can set a new signal handler, and the main thread will be the only one to 0042 receive signals (this is enforced by the Python :mod:`signal` module, even 0043 if the underlying thread implementation supports sending signals to 0044 individual threads). This means that signals can't be used as a means of 0045 inter-thread communication. Use locks instead. 0046 0047 The variables defined in the :mod:`signal` module are: 0048 0049 0050 """ 0051 """ 0052 This is one of two standard signal handling options; it will simply perform 0053 the default function for the signal. For example, on most systems the 0054 default action for :const:`SIGQUIT` is to dump core and exit, while the 0055 default action for :const:`SIGCHLD` is to simply ignore it. 0056 0057 0058 """ 0059 SIG_DFL = None 0060 """ 0061 This is another standard signal handler, which will simply ignore the given 0062 signal. 0063 0064 0065 """ 0066 SIG_IGN = None 0067 """ 0068 All the signal numbers are defined symbolically. For example, the hangup signal 0069 is defined as :const:`signal.SIGHUP`; the variable names are identical to the 0070 names used in C programs, as found in ``<signal.h>``. The Unix man page for 0071 ':cfunc:`signal`' lists the existing signals (on some systems this is 0072 :manpage:`signal(2)`, on others the list is in :manpage:`signal(7)`). Note that 0073 not all systems define the same set of signal names; only those names defined by 0074 the system are defined by this module. 0075 0076 0077 """ 0078 SIG = None 0079 """ 0080 The signal corresponding to the CTRL+C keystroke event. This signal can 0081 only be used with :func:`os.kill`. 0082 0083 Availability: Windows. 0084 0085 """ 0086 CTRL_C_EVENT = None 0087 """ 0088 The signal corresponding to the CTRL+BREAK keystroke event. This signal can 0089 only be used with :func:`os.kill`. 0090 0091 Availability: Windows. 0092 0093 """ 0094 CTRL_BREAK_EVENT = None 0095 """ 0096 One more than the number of the highest signal number. 0097 0098 0099 """ 0100 NSIG = None 0101 """ 0102 Decrements interval timer in real time, and delivers :const:`SIGALRM` upon expiration. 0103 0104 0105 """ 0106 ITIMER_REAL = None 0107 """ 0108 Decrements interval timer only when the process is executing, and delivers 0109 SIGVTALRM upon expiration. 0110 0111 0112 """ 0113 ITIMER_VIRTUAL = None 0114 """ 0115 Decrements interval timer both when the process executes and when the 0116 system is executing on behalf of the process. Coupled with ITIMER_VIRTUAL, 0117 this timer is usually used to profile the time spent by the application 0118 in user and kernel space. SIGPROF is delivered upon expiration. 0119 0120 0121 The :mod:`signal` module defines one exception: 0122 0123 """ 0124 ITIMER_PROF = None 0125 def alarm(time): 0126 """ 0127 If *time* is non-zero, this function requests that a :const:`SIGALRM` signal be 0128 sent to the process in *time* seconds. Any previously scheduled alarm is 0129 canceled (only one alarm can be scheduled at any time). The returned value is 0130 then the number of seconds before any previously set alarm was to have been 0131 delivered. If *time* is zero, no alarm is scheduled, and any scheduled alarm is 0132 canceled. If the return value is zero, no alarm is currently scheduled. (See 0133 the Unix man page :manpage:`alarm(2)`.) Availability: Unix. 0134 0135 0136 """ 0137 pass 0138 0139 def getsignal(signalnum): 0140 """ 0141 Return the current signal handler for the signal *signalnum*. The returned value 0142 may be a callable Python object, or one of the special values 0143 :const:`signal.SIG_IGN`, :const:`signal.SIG_DFL` or :const:`None`. Here, 0144 :const:`signal.SIG_IGN` means that the signal was previously ignored, 0145 :const:`signal.SIG_DFL` means that the default way of handling the signal was 0146 previously in use, and ``None`` means that the previous signal handler was not 0147 installed from Python. 0148 0149 0150 """ 0151 pass 0152 0153 def pause(): 0154 """ 0155 Cause the process to sleep until a signal is received; the appropriate handler 0156 will then be called. Returns nothing. Not on Windows. (See the Unix man page 0157 :manpage:`signal(2)`.) 0158 0159 0160 """ 0161 pass 0162 0163 def setitimer(which,seconds,interval): 0164 """ 0165 Sets given interval timer (one of :const:`signal.ITIMER_REAL`, 0166 :const:`signal.ITIMER_VIRTUAL` or :const:`signal.ITIMER_PROF`) specified 0167 by *which* to fire after *seconds* (float is accepted, different from 0168 :func:`alarm`) and after that every *interval* seconds. The interval 0169 timer specified by *which* can be cleared by setting seconds to zero. 0170 0171 When an interval timer fires, a signal is sent to the process. 0172 The signal sent is dependent on the timer being used; 0173 :const:`signal.ITIMER_REAL` will deliver :const:`SIGALRM`, 0174 :const:`signal.ITIMER_VIRTUAL` sends :const:`SIGVTALRM`, 0175 and :const:`signal.ITIMER_PROF` will deliver :const:`SIGPROF`. 0176 0177 The old values are returned as a tuple: (delay, interval). 0178 0179 Attempting to pass an invalid interval timer will cause an 0180 :exc:`ItimerError`. Availability: Unix. 0181 0182 """ 0183 pass 0184 0185 def getitimer(which): 0186 """ 0187 Returns current value of a given interval timer specified by *which*. 0188 Availability: Unix. 0189 0190 """ 0191 pass 0192 0193 def set_wakeup_fd(fd): 0194 """ 0195 Set the wakeup fd to *fd*. When a signal is received, a ``'\0'`` byte is 0196 written to the fd. This can be used by a library to wakeup a poll or select 0197 call, allowing the signal to be fully processed. 0198 0199 The old wakeup fd is returned. *fd* must be non-blocking. It is up to the 0200 library to remove any bytes before calling poll or select again. 0201 0202 When threads are enabled, this function can only be called from the main thread; 0203 attempting to call it from other threads will cause a :exc:`ValueError` 0204 exception to be raised. 0205 0206 """ 0207 pass 0208 0209 def siginterrupt(signalnum,flag): 0210 """ 0211 Change system call restart behaviour: if *flag* is :const:`False`, system 0212 calls will be restarted when interrupted by signal *signalnum*, otherwise 0213 system calls will be interrupted. Returns nothing. Availability: Unix (see 0214 the man page :manpage:`siginterrupt(3)` for further information). 0215 0216 Note that installing a signal handler with :func:`signal` will reset the 0217 restart behaviour to interruptible by implicitly calling 0218 :cfunc:`siginterrupt` with a true *flag* value for the given signal. 0219 0220 """ 0221 pass 0222