[Python-checkins] r76110 - sandbox/trunk/newgil/Python/ceval_gil.h

[antoine.pitrou]

Author: antoine.pitrou
Date: Wed Nov  4 22:04:05 2009
New Revision: 76110

Log:
Document the implementation



Modified:
   sandbox/trunk/newgil/Python/ceval_gil.h

Modified: sandbox/trunk/newgil/Python/ceval_gil.h
==============================================================================
--- sandbox/trunk/newgil/Python/ceval_gil.h	(original)
+++ sandbox/trunk/newgil/Python/ceval_gil.h	Wed Nov  4 22:04:05 2009
@@ -25,6 +25,40 @@
 /* #define TRACE_PRIO */
 
 
+/*
+   Notes about the implementation:
+   
+   - The GIL is just a boolean variable (gil_locked) whose access is protected
+     by a mutex, and whose changes are signalled by a condition variable. The
+     mutex itself is rarely taken and, therefore, mostly uncontended.
+
+   - In the GIL-holding thread, the main loop (PyEval_EvalFrameEx) must be
+     able to release the GIL on demand by another thread. A volatile boolean
+     variable (gil_drop_request) is used for that purpose, which is checked
+     at every turn of the eval loop.
+      
+      [Actually, another volatile boolean variable (eval_breaker) is used
+       which aggregates several conditions into one. Volatile booleans are
+       ok as signalling means since Python is run on cache-coherent
+       architectures only.]
+
+   - A thread wanting to take the GIL will first wait for a given amount of
+     time before setting gil_drop_request. This amount of time defines the
+     ideal thread switching period. It is available for the user to read
+     and modify using `sys.{get,set}switchinterval()`.
+
+   - Forced thread switching when releasing the GIL is implemented. When
+     a thread releases the GIL and gil_drop_request is set, that thread
+     ensures that another GIL-awaiting thread gets scheduled. It does so
+     by waiting on a variable (gil_last_holder) controlled through another
+     {mutex, condition} pair.
+
+   - An optional policy mechanism, priority requests, is currently disabled.
+     The intent was to further improve the latency of some types of GIL-taking
+     activities, such as being woken up on a socket. If it is confirmed that
+     this feature is unnecessary, support code should be removed.
+*/
+
 #ifndef _POSIX_THREADS
 /* This means pthreads are not implemented in libc headers, hence the macro
    not present in unistd.h. But they still can be implemented as an external