merge r68915 to py3k
diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst
index 6178851..f3dd23e 100644
--- a/Doc/library/multiprocessing.rst
+++ b/Doc/library/multiprocessing.rst
@@ -1857,30 +1857,74 @@
Returns the logger used by :mod:`multiprocessing`. If necessary, a new one
will be created.
- When first created the logger has level :data:`logging.NOTSET` and has a
- handler which sends output to :data:`sys.stderr` using format
- ``'[%(levelname)s/%(processName)s] %(message)s'``. (The logger allows use of
- the non-standard ``'%(processName)s'`` format.) Message sent to this logger
- will not by default propagate to the root logger.
+ When first created the logger has level :data:`logging.NOTSET` and no
+ default handler. Messages sent to this logger will not by default propagate
+ to the root logger.
Note that on Windows child processes will only inherit the level of the
parent process's logger -- any other customization of the logger will not be
inherited.
+.. currentmodule:: multiprocessing
+.. function:: log_to_stderr()
+
+ This function performs a call to :func:`get_logger` but in addition to
+ returning the logger created by get_logger, it adds a handler which sends
+ output to :data:`sys.stderr` using format
+ ``'[%(levelname)s/%(processName)s] %(message)s'``.
+
Below is an example session with logging turned on::
>>> import multiprocessing, logging
- >>> logger = multiprocessing.get_logger()
+ >>> logger = multiprocessing.log_to_stderr()
>>> logger.setLevel(logging.INFO)
>>> logger.warning('doomed')
[WARNING/MainProcess] doomed
>>> m = multiprocessing.Manager()
[INFO/SyncManager-1] child process calling self.run()
- [INFO/SyncManager-1] manager bound to '\\\\.\\pipe\\pyc-2776-0-lj0tfa'
+ [INFO/SyncManager-1] created temp directory /.../pymp-Wh47O_
+ [INFO/SyncManager-1] manager serving at '/.../listener-lWsERs'
>>> del m
[INFO/MainProcess] sending shutdown message to manager
[INFO/SyncManager-1] manager exiting with exitcode 0
+In addition to having these two logging functions, the multiprocessing also
+exposes two additional logging level attributes. These are :const:`SUBWARNING`
+and :const:`SUBDEBUG`. The table below illustrates where theses fit in the
+normal level hierarchy.
+
++----------------+----------------+
+| Level | Numeric value |
++================+================+
+| ``SUBWARNING`` | 25 |
++----------------+----------------+
+| ``SUBDEBUG`` | 5 |
++----------------+----------------+
+
+For a full table of logging levels, see the :mod:`logging` module.
+
+These additional logging levels are used primarily for certain debug messages
+within the multiprocessing module. Below is the same example as above, except
+with :const:`SUBDEBUG` enabled::
+
+ >>> import multiprocessing, logging
+ >>> logger = multiprocessing.log_to_stderr()
+ >>> logger.setLevel(multiprocessing.SUBDEBUG)
+ >>> logger.warning('doomed')
+ [WARNING/MainProcess] doomed
+ >>> m = multiprocessing.Manager()
+ [INFO/SyncManager-1] child process calling self.run()
+ [INFO/SyncManager-1] created temp directory /.../pymp-djGBXN
+ [INFO/SyncManager-1] manager serving at '/.../pymp-djGBXN/listener-knBYGe'
+ >>> del m
+ [SUBDEBUG/MainProcess] finalizer calling ...
+ [INFO/MainProcess] sending shutdown message to manager
+ [DEBUG/SyncManager-1] manager received shutdown message
+ [SUBDEBUG/SyncManager-1] calling <Finalize object, callback=unlink, ...
+ [SUBDEBUG/SyncManager-1] finalizer calling <built-in function unlink> ...
+ [SUBDEBUG/SyncManager-1] calling <Finalize object, dead>
+ [SUBDEBUG/SyncManager-1] finalizer calling <function rmtree at 0x5aa730> ...
+ [INFO/SyncManager-1] manager exiting with exitcode 0
The :mod:`multiprocessing.dummy` module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~