[Python-checkins] python/nondist/peps pep-0311.txt,1.2,1.3
mhammond@users.sourceforge.net
mhammond@users.sourceforge.net
Fri, 18 Apr 2003 18:11:26 -0700
Update of /cvsroot/python/python/nondist/peps
In directory sc8-pr-cvs1:/tmp/cvs-serv23710
Modified Files:
pep-0311.txt
Log Message:
Updated version with new names and no (known!) outstanding issues.
Index: pep-0311.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/peps/pep-0311.txt,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** pep-0311.txt 14 Feb 2003 14:51:27 -0000 1.2
--- pep-0311.txt 19 Apr 2003 01:11:23 -0000 1.3
***************
*** 8,32 ****
Content-Type: text/plain
Created: 05-Feb-2003
! Post-History: 05-Feb-2003 14-Feb-2003
!
!
! Open Issues
!
! This is where I note comments from people that are yet to be
! resolved.
!
! - JustvR prefers a PyGIL prefix over PyAutoThreadState.
! - JackJ notes that the "Auto" prefix will look a little silly
! in a few years, assuming this becomes the standard way of
! managing the lock. He doesn't really like Just's "GIL", and
! suggested "PyIntLock"
! - JackJ prefers "Acquire" over "Ensure", even though the semantics
! are different than for other "Acquire" functions in the API.
! Mark still prefers Ensure for exactly this reason.
! - Mark notes Dutch people must love names, and still remembers
! "pulling dead cows from the ditch" (but has forgotten the
! Dutch!) He also hopes Jack remembers the reference <wink>.
! - Should we provide Py_AUTO_THREAD_STATE macros?
! - Is my "Limitation" regarding PyEval_InitThreads() OK?
--- 8,12 ----
Content-Type: text/plain
Created: 05-Feb-2003
! Post-History: 05-Feb-2003 14-Feb-2003 19-Apr-2003
***************
*** 140,186 ****
platforms built with WITH_THREAD defined.
! The intent is that an extension author be able to use a small,
! well-defined "prologue dance", at any time and on any thread, and
! assuming Python has correctly been initialized, this dance will
! ensure Python is ready to be used on that thread. After the
! extension has finished with Python, it must also perform an
! "epilogue dance" to release any resources previously acquired.
! Ideally, these dances can be expressed in a single line.
Specifically, the following new APIs are proposed:
! /* 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, so
! long as each call is matched with a call to
! PyAutoThreadState_Release()
!
! The return value is an opaque "handle" to the thread state when
! PyAutoThreadState_Ensure() was called, and must be passed to
! PyAutoThreadState_Release() to ensure Python is left in the same
! state.
!
! When the function returns, the current thread will hold the GIL.
! Thus, the GIL is held by the thread until
! PyAutoThreadState_Release() is called. (Note that as happens now
! in Python, calling a Python API function may indeed cause a
! thread-switch and therefore a GIL ownership change. However,
! Python guarantees that when the API function returns, the GIL will
! again be owned by the thread making the call)
!
! Failure is a fatal error.
*/
! PyAutoThreadState_State PyAutoThreadState_Ensure(void);
!
! /* Release any resources previously acquired. After this call,
! Python's state will be the same as it was prior to the
! corresponding PyAutoThreadState_Ensure call (but generally this
! state will be unknown to the caller, hence the use of the
! AutoThreadState API.)
! Every call to PyAutoThreadState_Ensure must be matched by a
! call to PyAutoThreadState_Release on the same thread.
*/
! void PyAutoThreadState_Release(PyAutoThreadState_State state);
Common usage will be:
--- 120,165 ----
platforms built with WITH_THREAD defined.
! The intent is that assuming Python has correctly been initialized,
! an extension author be able to use a small, well-defined "prologue
! dance", at any time and on any thread, which will ensure Python
! is ready to be used on that thread. After the extension has
! finished with Python, it must also perform an "epilogue dance" to
! release any resources previously acquired. Ideally, these dances
! can be expressed in a single line.
Specifically, the following new APIs are proposed:
! /* 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 so long as each call is matched with a call to
! PyGILState_Release(). In general, other thread-state APIs may
! be used between _Ensure() and _Release() calls, so long as the
! thread-state is restored to its previous state before the Release().
! For example, normal use of the Py_BEGIN_ALLOW_THREADS/
! Py_END_ALLOW_THREADS macros are acceptable.
!
! The return value is an opaque "handle" to the thread state when
! PyGILState_Acquire() was called, and must be passed to
! PyGILState_Release() to ensure Python is left in the same state. Even
! though recursive calls are allowed, these handles can *not* be
! shared - each unique call to PyGILState_Ensure must save the handle
! for its call to PyGILState_Release.
!
! When the function returns, the current thread will hold the GIL.
!
! Failure is a fatal error.
*/
! PyAPI_FUNC(PyGILState_STATE) PyGILState_Ensure(void);
! /* Release any resources previously acquired. After this call, Python's
! state will be the same as it was prior to the corresponding
! PyGILState_Acquire call (but generally this state will be unknown to
! the caller, hence the use of the GILState API.)
!
! Every call to PyGILState_Ensure must be matched by a call to
! PyGILState_Release on the same thread.
*/
! PyAPI_FUNC(void) PyGILState_Release(PyGILState_STATE);
Common usage will be:
***************
*** 189,197 ****
{
/* ensure we hold the lock */
! PyAutoThreadState_State state = PyAutoThreadState_Ensure();
/* Use the Python API */
...
/* Restore the state of Python */
! PyAutoThreadState_Release(state);
}
--- 168,176 ----
{
/* ensure we hold the lock */
! PyGILState_STATE state = PyGILState_Ensure();
/* Use the Python API */
...
/* Restore the state of Python */
! PyGILState_Release(state);
}
***************
*** 199,204 ****
Design and Implementation
! The general operation of PyAutoThreadState_Ensure() will be:
!
- assert Python is initialized.
- Get a PyThreadState for the current thread, creating and saving
--- 178,182 ----
Design and Implementation
! The general operation of PyGILState_Ensure() will be:
- assert Python is initialized.
- Get a PyThreadState for the current thread, creating and saving
***************
*** 213,220 ****
- assert our thread currently holds the lock.
! - If old state indicates lock as previously unlocked, release GIL.
- Decrement the PyAutoThreadState_Ensure counter for the thread.
- If counter == 0:
! - release the PyThreadState.
- forget the ThreadState as being owned by the thread.
- return
--- 191,198 ----
- assert our thread currently holds the lock.
! - If old state indicates lock was previously unlocked, release GIL.
- Decrement the PyAutoThreadState_Ensure counter for the thread.
- If counter == 0:
! - release and delete the PyThreadState.
- forget the ThreadState as being owned by the thread.
- return