diff options
author | Benjamin Peterson <benjamin@python.org> | 2009-04-11 19:48:14 (GMT) |
---|---|---|
committer | Benjamin Peterson <benjamin@python.org> | 2009-04-11 19:48:14 (GMT) |
commit | ef3e4c2b4d5f07acc33c66d01063fcdf00b7b7d9 (patch) | |
tree | 953ceebb0269e299b933471f323d9a50de989e9d /Doc | |
parent | da2ba336da60c2a853df3a95dbe8921e104dd4be (diff) | |
download | cpython-ef3e4c2b4d5f07acc33c66d01063fcdf00b7b7d9.zip cpython-ef3e4c2b4d5f07acc33c66d01063fcdf00b7b7d9.tar.gz cpython-ef3e4c2b4d5f07acc33c66d01063fcdf00b7b7d9.tar.bz2 |
Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r70980 | jack.diederich | 2009-04-01 15:26:13 -0500 (Wed, 01 Apr 2009) | 3 lines
bounds check arguments to mmap.move(). All of them. Really.
fixes crasher on OS X 10.5
........
r71059 | mark.dickinson | 2009-04-02 13:39:37 -0500 (Thu, 02 Apr 2009) | 2 lines
sys.long_info attributes should be ints, not longs
........
r71225 | georg.brandl | 2009-04-05 06:54:07 -0500 (Sun, 05 Apr 2009) | 1 line
#5580: no need to use parentheses when converterr() argument is actually a type description.
........
r71234 | georg.brandl | 2009-04-05 08:16:35 -0500 (Sun, 05 Apr 2009) | 1 line
Whitespace normalization.
........
r71241 | georg.brandl | 2009-04-05 09:48:49 -0500 (Sun, 05 Apr 2009) | 1 line
#5471: fix expanduser() for $HOME set to "/".
........
r71243 | georg.brandl | 2009-04-05 10:14:29 -0500 (Sun, 05 Apr 2009) | 1 line
#5432: make plistlib docstring a raw string, since it contains examples with backslash escapes.
........
r71249 | georg.brandl | 2009-04-05 11:30:43 -0500 (Sun, 05 Apr 2009) | 1 line
#5444: adapt make.bat to new htmlhelp output file name.
........
r71251 | georg.brandl | 2009-04-05 12:17:42 -0500 (Sun, 05 Apr 2009) | 1 line
#5298: clarify docs about GIL by using more consistent wording.
........
r71255 | georg.brandl | 2009-04-05 13:34:58 -0500 (Sun, 05 Apr 2009) | 1 line
#602893: add indicator for current line in cgitb that doesnt rely on styling alone.
........
r71266 | georg.brandl | 2009-04-05 15:23:13 -0500 (Sun, 05 Apr 2009) | 1 line
Normalize issue referencing style.
........
r71299 | gregory.p.smith | 2009-04-05 18:43:58 -0500 (Sun, 05 Apr 2009) | 3 lines
Fixes issue5705: os.setuid() and friends did not accept the same range of
values that pwd.getpwnam() returns.
........
r71329 | benjamin.peterson | 2009-04-06 16:53:33 -0500 (Mon, 06 Apr 2009) | 1 line
add create_connection to __all__ #5711
........
r71397 | georg.brandl | 2009-04-08 11:36:39 -0500 (Wed, 08 Apr 2009) | 1 line
Remove redundant backtick.
........
r71398 | georg.brandl | 2009-04-08 11:39:04 -0500 (Wed, 08 Apr 2009) | 1 line
Update ignore file for suspicious builder.
........
r71486 | andrew.kuchling | 2009-04-11 11:18:14 -0500 (Sat, 11 Apr 2009) | 1 line
Re-word
........
Diffstat (limited to 'Doc')
-rw-r--r-- | Doc/c-api/buffer.rst | 2 | ||||
-rw-r--r-- | Doc/c-api/init.rst | 157 | ||||
-rw-r--r-- | Doc/distutils/setupscript.rst | 6 | ||||
-rw-r--r-- | Doc/make.bat | 3 | ||||
-rw-r--r-- | Doc/tools/sphinxext/susp-ignored.csv | 2 |
5 files changed, 87 insertions, 83 deletions
diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst index c46028b..a172e53 100644 --- a/Doc/c-api/buffer.rst +++ b/Doc/c-api/buffer.rst @@ -239,7 +239,7 @@ Buffer related functions | :cmacro:`PyBUF_FULL` | This is equivalent to ``(PyBUF_INDIRECT | | | | PyBUF_FORMAT | PyBUF_WRITABLE)``. | +------------------------------+---------------------------------------------------+ - | :cmacro:`PyBUF_FULL_RO`` | This is equivalent to ``(PyBUF_INDIRECT | | + | :cmacro:`PyBUF_FULL_RO` | This is equivalent to ``(PyBUF_INDIRECT | | | | PyBUF_FORMAT)``. | +------------------------------+---------------------------------------------------+ | :cmacro:`PyBUF_CONTIG` | This is equivalent to ``(PyBUF_ND | | diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index a6f8b9f..d3a2a3b 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -391,12 +391,12 @@ Thread State and the Global Interpreter Lock single: lock, interpreter The Python interpreter is not fully thread safe. In order to support -multi-threaded Python programs, there's a global lock that must be held by the -current thread before it can safely access Python objects. Without the lock, -even the simplest operations could cause problems in a multi-threaded program: -for example, when two threads simultaneously increment the reference count of -the same object, the reference count could end up being incremented only once -instead of twice. +multi-threaded Python programs, there's a global lock, called the :dfn:`global +interpreter lock` or :dfn:`GIL`, that must be held by the current thread before +it can safely access Python objects. Without the lock, even the simplest +operations could cause problems in a multi-threaded program: for example, when +two threads simultaneously increment the reference count of the same object, the +reference count could end up being incremented only once instead of twice. .. index:: single: setcheckinterval() (in module sys) @@ -425,9 +425,9 @@ This is easy enough in most cases. Most code manipulating the global interpreter lock has the following simple structure:: Save the thread state in a local variable. - Release the interpreter lock. + Release the global interpreter lock. ...Do some blocking I/O operation... - Reacquire the interpreter lock. + Reacquire the global interpreter lock. Restore the thread state from the local variable. This is so common that a pair of macros exists to simplify it:: @@ -444,7 +444,7 @@ The :cmacro:`Py_BEGIN_ALLOW_THREADS` macro opens a new block and declares a hidden local variable; the :cmacro:`Py_END_ALLOW_THREADS` macro closes the block. Another advantage of using these two macros is that when Python is compiled without thread support, they are defined empty, thus saving the thread -state and lock manipulations. +state and GIL manipulations. When thread support is enabled, the block above expands to the following code:: @@ -476,7 +476,7 @@ There are some subtle differences; in particular, :cfunc:`PyEval_RestoreThread` saves and restores the value of the global variable :cdata:`errno`, since the lock manipulation does not guarantee that :cdata:`errno` is left alone. Also, when thread support is disabled, :cfunc:`PyEval_SaveThread` and -:cfunc:`PyEval_RestoreThread` don't manipulate the lock; in this case, +:cfunc:`PyEval_RestoreThread` don't manipulate the GIL; in this case, :cfunc:`PyEval_ReleaseLock` and :cfunc:`PyEval_AcquireLock` are not available. This is done so that dynamically loaded extensions compiled with thread support enabled can be loaded by an interpreter that was compiled with disabled thread @@ -559,16 +559,16 @@ supports the creation of additional interpreters (using .. index:: module: _thread - When only the main thread exists, no lock operations are needed. This is a + When only the main thread exists, no GIL operations are needed. This is a common situation (most Python programs do not use threads), and the lock - operations slow the interpreter down a bit. Therefore, the lock is not created - initially. This situation is equivalent to having acquired the lock: when - there is only a single thread, all object accesses are safe. Therefore, when - this function initializes the lock, it also acquires it. Before the Python - :mod:`_thread` module creates a new thread, knowing that either it has the lock - or the lock hasn't been created yet, it calls :cfunc:`PyEval_InitThreads`. When - this call returns, it is guaranteed that the lock has been created and that the - calling thread has acquired it. + operations slow the interpreter down a bit. Therefore, the lock is not + created initially. This situation is equivalent to having acquired the lock: + when there is only a single thread, all object accesses are safe. Therefore, + when this function initializes the global interpreter lock, it also acquires + it. Before the Python :mod:`_thread` module creates a new thread, knowing + that either it has the lock or the lock hasn't been created yet, it calls + :cfunc:`PyEval_InitThreads`. When this call returns, it is guaranteed that + the lock has been created and that the calling thread has acquired it. It is **not** safe to call this function when it is unknown which thread (if any) currently has the global interpreter lock. @@ -579,7 +579,7 @@ supports the creation of additional interpreters (using .. cfunction:: int PyEval_ThreadsInitialized() Returns a non-zero value if :cfunc:`PyEval_InitThreads` has been called. This - function can be called without holding the lock, and therefore can be used to + function can be called without holding the GIL, and therefore can be used to avoid calls to the locking API when running single-threaded. This function is not available when thread support is disabled at compile time. @@ -617,20 +617,20 @@ supports the creation of additional interpreters (using .. cfunction:: PyThreadState* PyEval_SaveThread() - Release the interpreter lock (if it has been created and thread support is - enabled) and reset the thread state to *NULL*, returning the previous thread - state (which is not *NULL*). If the lock has been created, the current thread - must have acquired it. (This function is available even when thread support is - disabled at compile time.) + Release the global interpreter lock (if it has been created and thread + support is enabled) and reset the thread state to *NULL*, returning the + previous thread state (which is not *NULL*). If the lock has been created, + the current thread must have acquired it. (This function is available even + when thread support is disabled at compile time.) .. cfunction:: void PyEval_RestoreThread(PyThreadState *tstate) - Acquire the interpreter lock (if it has been created and thread support is - enabled) and set the thread state to *tstate*, which must not be *NULL*. If the - lock has been created, the current thread must not have acquired it, otherwise - deadlock ensues. (This function is available even when thread support is - disabled at compile time.) + Acquire the global interpreter lock (if it has been created and thread + support is enabled) and set the thread state to *tstate*, which must not be + *NULL*. If the lock has been created, the current thread must not have + acquired it, otherwise deadlock ensues. (This function is available even + when thread support is disabled at compile time.) .. cfunction:: void PyEval_ReInitThreads() @@ -674,60 +674,61 @@ example usage in the Python source distribution. declaration. It is a no-op when thread support is disabled at compile time. All of the following functions are only available when thread support is enabled -at compile time, and must be called only when the interpreter lock has been -created. +at compile time, and must be called only when the global interpreter lock has +been created. .. cfunction:: PyInterpreterState* PyInterpreterState_New() - Create a new interpreter state object. The interpreter lock need not be held, - but may be held if it is necessary to serialize calls to this function. + Create a new interpreter state object. The global interpreter lock need not + be held, but may be held if it is necessary to serialize calls to this + function. .. cfunction:: void PyInterpreterState_Clear(PyInterpreterState *interp) - Reset all information in an interpreter state object. The interpreter lock must - be held. + Reset all information in an interpreter state object. The global interpreter + lock must be held. .. cfunction:: void PyInterpreterState_Delete(PyInterpreterState *interp) - Destroy an interpreter state object. The interpreter lock need not be held. - The interpreter state must have been reset with a previous call to + Destroy an interpreter state object. The global interpreter lock need not be + held. The interpreter state must have been reset with a previous call to :cfunc:`PyInterpreterState_Clear`. .. cfunction:: PyThreadState* PyThreadState_New(PyInterpreterState *interp) - Create a new thread state object belonging to the given interpreter object. The - interpreter lock need not be held, but may be held if it is necessary to - serialize calls to this function. + Create a new thread state object belonging to the given interpreter object. + The global interpreter lock need not be held, but may be held if it is + necessary to serialize calls to this function. .. cfunction:: void PyThreadState_Clear(PyThreadState *tstate) - Reset all information in a thread state object. The interpreter lock must be - held. + Reset all information in a thread state object. The global interpreter lock + must be held. .. cfunction:: void PyThreadState_Delete(PyThreadState *tstate) - Destroy a thread state object. The interpreter lock need not be held. The - thread state must have been reset with a previous call to + Destroy a thread state object. The global interpreter lock need not be held. + The thread state must have been reset with a previous call to :cfunc:`PyThreadState_Clear`. .. cfunction:: PyThreadState* PyThreadState_Get() - Return the current thread state. The interpreter lock must be held. When the - current thread state is *NULL*, this issues a fatal error (so that the caller - needn't check for *NULL*). + Return the current thread state. The global interpreter lock must be held. + When the current thread state is *NULL*, this issues a fatal error (so that + the caller needn't check for *NULL*). .. cfunction:: PyThreadState* PyThreadState_Swap(PyThreadState *tstate) Swap the current thread state with the thread state given by the argument - *tstate*, which may be *NULL*. The interpreter lock must be held. + *tstate*, which may be *NULL*. The global interpreter lock must be held. .. cfunction:: PyObject* PyThreadState_GetDict() @@ -752,14 +753,15 @@ created. .. cfunction:: PyGILState_STATE PyGILState_Ensure() - Ensure that the current thread is ready to call the Python C API regardless of - the current state of Python, or of its thread lock. This may be called as many - times as desired by a thread as long as each call is matched with a call to - :cfunc:`PyGILState_Release`. In general, other thread-related APIs may be used - between :cfunc:`PyGILState_Ensure` and :cfunc:`PyGILState_Release` calls as long - as the thread state is restored to its previous state before the Release(). For - example, normal usage of the :cmacro:`Py_BEGIN_ALLOW_THREADS` and - :cmacro:`Py_END_ALLOW_THREADS` macros is acceptable. + Ensure that the current thread is ready to call the Python C API regardless + of the current state of Python, or of the global interpreter lock. This may + be called as many times as desired by a thread as long as each call is + matched with a call to :cfunc:`PyGILState_Release`. In general, other + thread-related APIs may be used between :cfunc:`PyGILState_Ensure` and + :cfunc:`PyGILState_Release` calls as long as the thread state is restored to + its previous state before the Release(). For example, normal usage of the + :cmacro:`Py_BEGIN_ALLOW_THREADS` and :cmacro:`Py_END_ALLOW_THREADS` macros is + acceptable. The return value is an opaque "handle" to the thread state when :cfunc:`PyGILState_Ensure` was called, and must be passed to @@ -793,35 +795,34 @@ pointer and a void argument. .. index:: single: setcheckinterval() (in module sys) -Every check interval, when the interpreter lock is released and reacquired, -python will also call any such provided functions. This can be used for -example by asynchronous IO handlers. The notification can be scheduled -from a worker thread and the actual call than made at the earliest -convenience by the main thread where it has possession of the global -interpreter lock and can perform any Python API calls. +Every check interval, when the global interpreter lock is released and +reacquired, python will also call any such provided functions. This can be used +for example by asynchronous IO handlers. The notification can be scheduled from +a worker thread and the actual call than made at the earliest convenience by the +main thread where it has possession of the global interpreter lock and can +perform any Python API calls. .. cfunction:: void Py_AddPendingCall( int (*func)(void *, void *arg) ) .. index:: single: Py_AddPendingCall() - Post a notification to the Python main thread. If successful, - *func* will be called with the argument *arg* at the earliest - convenience. *func* will be called having the global interpreter - lock held and can thus use the full Python API and can take any - action such as setting object attributes to signal IO completion. - It must return 0 on success, or -1 signalling an exception. - The notification function won't be interrupted to perform another - asynchronous notification recursively, - but it can still be interrupted to switch threads if the interpreter - lock is released, for example, if it calls back into python code. + Post a notification to the Python main thread. If successful, *func* will be + called with the argument *arg* at the earliest convenience. *func* will be + called having the global interpreter lock held and can thus use the full + Python API and can take any action such as setting object attributes to + signal IO completion. It must return 0 on success, or -1 signalling an + exception. The notification function won't be interrupted to perform another + asynchronous notification recursively, but it can still be interrupted to + switch threads if the global interpreter lock is released, for example, if it + calls back into python code. This function returns 0 on success in which case the notification has been - scheduled. Otherwise, for example if the notification buffer is full, - it returns -1 without setting any exception. + scheduled. Otherwise, for example if the notification buffer is full, it + returns -1 without setting any exception. - This function can be called on any thread, be it a Python thread or - some other system thread. If it is a Python thread, it doesn't matter if - it holds the global interpreter lock or not. + This function can be called on any thread, be it a Python thread or some + other system thread. If it is a Python thread, it doesn't matter if it holds + the global interpreter lock or not. .. versionadded:: 2.7 diff --git a/Doc/distutils/setupscript.rst b/Doc/distutils/setupscript.rst index 85089d0..2985437 100644 --- a/Doc/distutils/setupscript.rst +++ b/Doc/distutils/setupscript.rst @@ -334,9 +334,9 @@ Other options There are still some other options which can be used to handle special cases. -The :option:`optional` option is a boolean; if it is true, that specifies that -a build failure in the extension should not abort the build process, but simply -not install the failing extension. +The :option:`optional` option is a boolean; if it is true, +a build failure in the extension will not abort the build process, but +instead simply not install the failing extension. The :option:`extra_objects` option is a list of object files to be passed to the linker. These files must not have extensions, as the default extension for the diff --git a/Doc/make.bat b/Doc/make.bat index c18e08b..c51fc8d 100644 --- a/Doc/make.bat +++ b/Doc/make.bat @@ -4,6 +4,7 @@ setlocal set SVNROOT=http://svn.python.org/projects
if "%PYTHON%" EQU "" set PYTHON=..\pcbuild\python
if "%HTMLHELP%" EQU "" set HTMLHELP=%ProgramFiles%\HTML Help Workshop\hhc.exe
+if "%DISTVERSION%" EQU "" for /f "usebackq" %%v in (`%PYTHON% tools/sphinxext/patchlevel.py`) do set DISTVERSION=%%v
if "%1" EQU "" goto help
if "%1" EQU "html" goto build
@@ -52,7 +53,7 @@ if not exist build\%1 mkdir build\%1 if not exist build\doctrees mkdir build\doctrees
cmd /C %PYTHON% --version
cmd /C %PYTHON% tools\sphinx-build.py -b%1 -dbuild\doctrees . build\%*
-if "%1" EQU "htmlhelp" "%HTMLHELP%" build\htmlhelp\pydoc.hhp
+if "%1" EQU "htmlhelp" "%HTMLHELP%" build\htmlhelp\python%DISTVERSION:.=%.hhp
goto end
:end
diff --git a/Doc/tools/sphinxext/susp-ignored.csv b/Doc/tools/sphinxext/susp-ignored.csv index 7e1a289..3f987c7 100644 --- a/Doc/tools/sphinxext/susp-ignored.csv +++ b/Doc/tools/sphinxext/susp-ignored.csv @@ -48,6 +48,8 @@ library/hotshot,,:lineno,"ncalls tottime percall cumtime percall filename:li library/httplib,,:port,host:port library/imaplib,,:MM,"""DD-Mmm-YYYY HH:MM:SS +HHMM""" library/imaplib,,:SS,"""DD-Mmm-YYYY HH:MM:SS +HHMM""" +library/itertools,,:stop,elements from seq[start:stop:step] +library/itertools,,:step,elements from seq[start:stop:step] library/linecache,,:sys,"sys:x:3:3:sys:/dev:/bin/sh" library/logging,,:And, library/logging,,:package1, |