PEP 418: Rephrase sleep/suspend paragraphs

pep-0418.txt

@@ -697,8 +697,8 @@ Get more detail in the `documentation of the NTP daemon
 <http://doc.ntp.org/4.1.2/ntpd.htm>`_.
 
 
-Operating system clocks
+Operating system time functions
-=======================
+===============================
 
 Monotonic clocks
 ----------------
@@ -1139,43 +1139,14 @@ See also `QueryIdleProcessorCycleTime() function
 (cycle time for the idle thread of each processor)
 
 
-Sleep, suspend and monotonic time
+Sleep
-=================================
-
-Linux
 -----
 
-sleep() is not affected by system clock update.
+Suspend execution of the process for the given number of seconds.  Sleep is not
-
+affected by system clock update. Sleep is paused during system suspend. For
-On Linux, CLOCK_MONOTONIC and CLOCK_MONOTONIC_RAW includes time the
+example, if a process sleeps for 60 seconds and the system is suspended for 30
-system spends in sleep; but it does not include time spent in
+seconds in the middle of the sleep, the sleep duration is 90 seconds in the
-hibernation (ACPI S3 mode).  If the system clock jumps backward,
+real time.
-CLOCK_MONOTONIC and CLOCK_MONOTONIC_RAW are not affected.
-
-Other operating systems
------------------------
-
-On Windows, GetTickCount() and GetTickCount64() include time the system spends
-in sleep; sleep() is not affected by system clock update. The WM_POWERBROADCAST
-message is send to Windows application to notify them of power-management
-events (ex: ower status has changed).
-
-On FreeBSD 8, CLOCK_MONOTONIC include time the system spends in sleep;
-sleep() is not affected by system clock update.
-
-On OpenIndiana, CLOCK_MONOTONIC include time the system spends in
-sleep; sleep() is not affected by system clock update.
-
-On Mac OS X, mach_absolute_time() include time the system spends in
-sleep; sleep() is not affected by system clock update.  Sleep is
-interrupted during suspend. Read also: `Registering and unregistering for sleep
-and wake notifications
-<http://developer.apple.com/library/mac/#qa/qa1340/_index.html>`_ (Technical
-Q&A QA1340).
-
-
-Sleeping
-========
 
 Sleep can be interrupted by a signal: the function fails with EINTR.
 
@@ -1204,8 +1175,8 @@ WaitForSingleObject()     1 ms
 ========================  ==========
 
 
-Classic functions
+Functions
------------------
+^^^^^^^^^
 
  * sleep(seconds)
  * usleep(microseconds)
@@ -1216,7 +1187,7 @@ Classic functions
 
 
 clock_nanosleep
----------------
+^^^^^^^^^^^^^^^
 
 clock_nanosleep(clock_id, flags, nanoseconds, remaining): `Linux
 manpage of clock_nanosleep()
@@ -1233,7 +1204,7 @@ on a relative clock_nanosleep().
 
 
 select()
---------
+^^^^^^^^
 
 select(nfds, readfds, writefds, exceptfs, timeout).
 
@@ -1247,7 +1218,7 @@ high-) resolution timeouts <http://lwn.net/Articles/296578/>`_ and
 
 
 Other functions
----------------
+^^^^^^^^^^^^^^^
 
  * poll(), epoll()
  * sigtimedwait(). POSIX: "If the Monotonic Clock option is supported,
@@ -1264,6 +1235,21 @@ Other functions
    the same precision.
 
 
+System Standby
+==============
+
+The ACPI power state "S3" is as system standby mode, also called "Suspend to
+RAM". RAM remains powered.
+
+On Windows, the WM_POWERBROADCAST message is send to Windows application
+to notify them of power-management events (ex: ower status has changed).
+
+For Mac OS X, read `Registering and unregistering for sleep
+and wake notifications
+<http://developer.apple.com/library/mac/#qa/qa1340/_index.html>`_ (Technical
+Q&A QA1340).
+
+
 Alternatives: API design
 ========================