Merged revisions 61846-61847 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r61846 | martin.v.loewis | 2008-03-24 13:57:53 +0100 (Mo, 24 Mär 2008) | 2 lines

  Install 2to3 script.
........
  r61847 | martin.v.loewis | 2008-03-24 14:31:16 +0100 (Mo, 24 Mär 2008) | 2 lines

  Patch #2240: Implement signal.setitimer and signal.getitimer.
........

1 files changed, 60 insertions, 7 deletions

diff --git a/Doc/library/signal.rst b/Doc/library/signal.rst
index 2e5cae5..94863e1 100644
--- a/Doc/library/signal.rst
+++ b/Doc/library/signal.rst
@@ -39,12 +39,13 @@ rules for working with signals and their handlers:
 * 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`, or
-  :func:`pause`; 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.
+  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:
 
@@ -78,6 +79,36 @@ The variables defined in the :mod:`signal` module are:
 
    One more than the number of the highest signal number.
 
+
+.. data:: ITIMER_REAL    
+
+   Decrements interval timer in real time, and delivers 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:
 
 
@@ -110,6 +141,29 @@ The :mod:`signal` module defines the following functions:
    :manpage:`signal(2)`.)
 
 
+.. function:: setitimer(which, seconds[, interval])
+
+   Sets given itimer (one of :const:`signal.ITIMER_REAL`, 
+   :const:`signal.ITIMER_VIRTUAL` or :const:`signal.ITIMER_PROF`) especified
+   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.
+
+   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 itimer especified 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
@@ -124,7 +178,6 @@ The :mod:`signal` module defines the following functions:
    exception to be raised.
 
 
-
 .. function:: siginterrupt(signalnum, flag)
 
    Change system call restart behaviour: if *flag* is :const:`False`, system calls