diff -r ffa851df0825 -r 2fb8b9db1c86 symbian-qemu-0.9.1-12/python-2.6.1/Doc/library/signal.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/symbian-qemu-0.9.1-12/python-2.6.1/Doc/library/signal.rst Fri Jul 31 15:01:17 2009 +0100 @@ -0,0 +1,245 @@ + +:mod:`signal` --- Set handlers for asynchronous events +====================================================== + +.. module:: signal + :synopsis: Set handlers for asynchronous events. + + +This module provides mechanisms to use signal handlers in Python. Some general +rules for working with signals and their handlers: + +* A handler for a particular signal, once set, remains installed until it is + explicitly reset (Python emulates the BSD style interface regardless of the + underlying implementation), with the exception of the handler for + :const:`SIGCHLD`, which follows the underlying implementation. + +* There is no way to "block" signals temporarily from critical sections (since + this is not supported by all Unix flavors). + +* Although Python signal handlers are called asynchronously as far as the Python + user is concerned, they can only occur between the "atomic" instructions of the + Python interpreter. This means that signals arriving during long calculations + implemented purely in C (such as regular expression matches on large bodies of + text) may be delayed for an arbitrary amount of time. + +* When a signal arrives during an I/O operation, it is possible that the I/O + operation raises an exception after the signal handler returns. This is + dependent on the underlying Unix system's semantics regarding interrupted system + calls. + +* Because the C signal handler always returns, it makes little sense to catch + synchronous errors like :const:`SIGFPE` or :const:`SIGSEGV`. + +* Python installs a small number of signal handlers by default: :const:`SIGPIPE` + is ignored (so write errors on pipes and sockets can be reported as ordinary + Python exceptions) and :const:`SIGINT` is translated into a + :exc:`KeyboardInterrupt` exception. All of these can be overridden. + +* Some care must be taken if both signals and threads are used in the same + program. The fundamental thing to remember in using signals and threads + simultaneously is: always perform :func:`signal` operations in the main thread + of execution. Any thread can perform an :func:`alarm`, :func:`getsignal`, + :func:`pause`, :func:`setitimer` or :func:`getitimer`; only the main thread + can set a new signal handler, and the main thread will be the only one to + receive signals (this is enforced by the Python :mod:`signal` module, even + if the underlying thread implementation supports sending signals to + individual threads). This means that signals can't be used as a means of + inter-thread communication. Use locks instead. + +The variables defined in the :mod:`signal` module are: + + +.. data:: SIG_DFL + + This is one of two standard signal handling options; it will simply perform the + default function for the signal. For example, on most systems the default + action for :const:`SIGQUIT` is to dump core and exit, while the default action + for :const:`SIGCLD` is to simply ignore it. + + +.. data:: SIG_IGN + + This is another standard signal handler, which will simply ignore the given + signal. + + +.. data:: SIG* + + All the signal numbers are defined symbolically. For example, the hangup signal + is defined as :const:`signal.SIGHUP`; the variable names are identical to the + names used in C programs, as found in ````. The Unix man page for + ':cfunc:`signal`' lists the existing signals (on some systems this is + :manpage:`signal(2)`, on others the list is in :manpage:`signal(7)`). Note that + not all systems define the same set of signal names; only those names defined by + the system are defined by this module. + + +.. data:: NSIG + + One more than the number of the highest signal number. + + +.. data:: ITIMER_REAL + + Decrements interval timer in real time, and delivers :const:`SIGALRM` upon expiration. + + +.. data:: ITIMER_VIRTUAL + + Decrements interval timer only when the process is executing, and delivers + SIGVTALRM upon expiration. + + +.. data:: ITIMER_PROF + + Decrements interval timer both when the process executes and when the + system is executing on behalf of the process. Coupled with ITIMER_VIRTUAL, + this timer is usually used to profile the time spent by the application + in user and kernel space. SIGPROF is delivered upon expiration. + + +The :mod:`signal` module defines one exception: + +.. exception:: ItimerError + + Raised to signal an error from the underlying :func:`setitimer` or + :func:`getitimer` implementation. Expect this error if an invalid + interval timer or a negative time is passed to :func:`setitimer`. + This error is a subtype of :exc:`IOError`. + + +The :mod:`signal` module defines the following functions: + + +.. function:: alarm(time) + + If *time* is non-zero, this function requests that a :const:`SIGALRM` signal be + sent to the process in *time* seconds. Any previously scheduled alarm is + canceled (only one alarm can be scheduled at any time). The returned value is + then the number of seconds before any previously set alarm was to have been + delivered. If *time* is zero, no alarm is scheduled, and any scheduled alarm is + canceled. If the return value is zero, no alarm is currently scheduled. (See + the Unix man page :manpage:`alarm(2)`.) Availability: Unix. + + +.. function:: getsignal(signalnum) + + Return the current signal handler for the signal *signalnum*. The returned value + may be a callable Python object, or one of the special values + :const:`signal.SIG_IGN`, :const:`signal.SIG_DFL` or :const:`None`. Here, + :const:`signal.SIG_IGN` means that the signal was previously ignored, + :const:`signal.SIG_DFL` means that the default way of handling the signal was + previously in use, and ``None`` means that the previous signal handler was not + installed from Python. + + +.. function:: pause() + + Cause the process to sleep until a signal is received; the appropriate handler + will then be called. Returns nothing. Not on Windows. (See the Unix man page + :manpage:`signal(2)`.) + + +.. function:: setitimer(which, seconds[, interval]) + + Sets given interval timer (one of :const:`signal.ITIMER_REAL`, + :const:`signal.ITIMER_VIRTUAL` or :const:`signal.ITIMER_PROF`) specified + by *which* to fire after *seconds* (float is accepted, different from + :func:`alarm`) and after that every *interval* seconds. The interval + timer specified by *which* can be cleared by setting seconds to zero. + + When an interval timer fires, a signal is sent to the process. + The signal sent is dependent on the timer being used; + :const:`signal.ITIMER_REAL` will deliver :const:`SIGALRM`, + :const:`signal.ITIMER_VIRTUAL` sends :const:`SIGVTALRM`, + and :const:`signal.ITIMER_PROF` will deliver :const:`SIGPROF`. + + The old values are returned as a tuple: (delay, interval). + + Attempting to pass an invalid interval timer will cause a + :exc:`ItimerError`. + + .. versionadded:: 2.6 + + +.. function:: getitimer(which) + + Returns current value of a given interval timer specified by *which*. + + .. versionadded:: 2.6 + + +.. function:: set_wakeup_fd(fd) + + Set the wakeup fd to *fd*. When a signal is received, a ``'\0'`` byte is + written to the fd. This can be used by a library to wakeup a poll or select + call, allowing the signal to be fully processed. + + The old wakeup fd is returned. *fd* must be non-blocking. It is up to the + library to remove any bytes before calling poll or select again. + + When threads are enabled, this function can only be called from the main thread; + attempting to call it from other threads will cause a :exc:`ValueError` + exception to be raised. + + +.. function:: siginterrupt(signalnum, flag) + + Change system call restart behaviour: if *flag* is :const:`False`, system calls + will be restarted when interrupted by signal *signalnum*, otherwise system calls will + be interrupted. Returns nothing. Availability: Unix (see the man page + :manpage:`siginterrupt(3)` for further information). + + Note that installing a signal handler with :func:`signal` will reset the restart + behaviour to interruptible by implicitly calling :cfunc:`siginterrupt` with a true *flag* + value for the given signal. + + .. versionadded:: 2.6 + + +.. function:: signal(signalnum, handler) + + Set the handler for signal *signalnum* to the function *handler*. *handler* can + be a callable Python object taking two arguments (see below), or one of the + special values :const:`signal.SIG_IGN` or :const:`signal.SIG_DFL`. The previous + signal handler will be returned (see the description of :func:`getsignal` + above). (See the Unix man page :manpage:`signal(2)`.) + + When threads are enabled, this function can only be called from the main thread; + attempting to call it from other threads will cause a :exc:`ValueError` + exception to be raised. + + The *handler* is called with two arguments: the signal number and the current + stack frame (``None`` or a frame object; for a description of frame objects, see + the reference manual section on the standard type hierarchy or see the attribute + descriptions in the :mod:`inspect` module). + + +.. _signal-example: + +Example +------- + +Here is a minimal example program. It uses the :func:`alarm` function to limit +the time spent waiting to open a file; this is useful if the file is for a +serial device that may not be turned on, which would normally cause the +:func:`os.open` to hang indefinitely. The solution is to set a 5-second alarm +before opening the file; if the operation takes too long, the alarm signal will +be sent, and the handler raises an exception. :: + + import signal, os + + def handler(signum, frame): + print 'Signal handler called with signal', signum + raise IOError, "Couldn't open device!" + + # Set the signal handler and a 5-second alarm + signal.signal(signal.SIGALRM, handler) + signal.alarm(5) + + # This open() may hang indefinitely + fd = os.open('/dev/ttyS0', os.O_RDWR) + + signal.alarm(0) # Disable the alarm +