[Python-checkins] cpython: Move import lock-related functions to a separate doc section.

[antoine.pitrou]

http://hg.python.org/cpython/rev/31ac156000c8
changeset:   77014:31ac156000c8
user:        Antoine Pitrou <solipsis at pitrou.net>
date:        Thu May 17 19:00:35 2012 +0200
summary:
  Move import lock-related functions to a separate doc section.

files:
  Doc/library/imp.rst |  85 ++++++++++++++++----------------
  1 files changed, 43 insertions(+), 42 deletions(-)


diff --git a/Doc/library/imp.rst b/Doc/library/imp.rst
--- a/Doc/library/imp.rst
+++ b/Doc/library/imp.rst
@@ -107,48 +107,6 @@
    in ``sys.modules``.
 
 
-.. function:: lock_held()
-
-   Return ``True`` if the import lock is currently held, else ``False``. On
-   platforms without threads, always return ``False``.
-
-   On platforms with threads, a thread executing an import first holds a
-   global import lock, then sets up a per-module lock for the rest of the
-   import.  This blocks other threads from importing the same module until
-   the original import completes, preventing other threads from seeing
-   incomplete module objects constructed by the original thread.  An
-   exception is made for circular imports, which by construction have to
-   expose an incomplete module object at some point.
-
-   .. note::
-      Locking semantics of imports are an implementation detail which may
-      vary from release to release.  However, Python ensures that circular
-      imports work without any deadlocks.
-
-   .. versionchanged:: 3.3
-      In Python 3.3, the locking scheme has changed to per-module locks for
-      the most part.
-
-
-.. function:: acquire_lock()
-
-   Acquire the interpreter's global import lock for the current thread.
-   This lock should be used by import hooks to ensure thread-safety when
-   importing modules.
-
-   Once a thread has acquired the import lock, the same thread may acquire it
-   again without blocking; the thread must release it once for each time it has
-   acquired it.
-
-   On platforms without threads, this function does nothing.
-
-
-.. function:: release_lock()
-
-   Release the interpreter's global import lock. On platforms without
-   threads, this function does nothing.
-
-
 .. function:: reload(module)
 
    Reload a previously imported *module*.  The argument must be a module object, so
@@ -246,6 +204,49 @@
    magic number, as returned by :func:`get_magic`.
 
 
+The following functions help interact with the import system's internal
+locking mechanism.  Locking semantics of imports are an implementation
+detail which may vary from release to release.  However, Python ensures
+that circular imports work without any deadlocks.
+
+.. versionchanged:: 3.3
+   In Python 3.3, the locking scheme has changed to per-module locks for
+   the most part.  A global import lock is kept for some critical tasks,
+   such as initializing the per-module locks.
+
+
+.. function:: lock_held()
+
+   Return ``True`` if the global import lock is currently held, else
+   ``False``. On platforms without threads, always return ``False``.
+
+   On platforms with threads, a thread executing an import first holds a
+   global import lock, then sets up a per-module lock for the rest of the
+   import.  This blocks other threads from importing the same module until
+   the original import completes, preventing other threads from seeing
+   incomplete module objects constructed by the original thread.  An
+   exception is made for circular imports, which by construction have to
+   expose an incomplete module object at some point.
+
+.. function:: acquire_lock()
+
+   Acquire the interpreter's global import lock for the current thread.
+   This lock should be used by import hooks to ensure thread-safety when
+   importing modules.
+
+   Once a thread has acquired the import lock, the same thread may acquire it
+   again without blocking; the thread must release it once for each time it has
+   acquired it.
+
+   On platforms without threads, this function does nothing.
+
+
+.. function:: release_lock()
+
+   Release the interpreter's global import lock. On platforms without
+   threads, this function does nothing.
+
+
 The following constants with integer values, defined in this module, are used
 to indicate the search result of :func:`find_module`.
 

-- 
Repository URL: http://hg.python.org/cpython