thread_pthread.h: rename `gvl.acquired' to `gvl.owner' and document

`acquired' was an old boolean variable, but nowadays it is a
rb_thread_t pointer;  "gvl.owner" seems like a more appropriate
name.  And document the contended path including waitq, timer,
and timer_err.

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@64581 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 14 insertions, 4 deletions

diff --git a/thread_pthread.h b/thread_pthread.h
index c64018bb13..f2b7e598f7 100644
--- a/thread_pthread.h
+++ b/thread_pthread.h
@@ -47,11 +47,21 @@ typedef struct native_thread_data_struct {
 
 typedef struct rb_global_vm_lock_struct {
     /* fast path */
-    const struct rb_thread_struct *acquired;
-    rb_nativethread_lock_t lock;
+    const struct rb_thread_struct *owner;
+    rb_nativethread_lock_t lock; /* AKA vm->gvl.lock */
 
-    /* slow path */
-    struct list_head waitq;
+    /*
+     * slow path, protected by vm->gvl.lock
+     * - @waitq - FIFO queue of threads waiting for GVL
+     * - @timer - it handles timeslices for @owner.  It is any one thread
+     *   in @waitq, there is no @timer if @waitq is empty, but always
+     *   a @timer if @waitq has entries
+     * - @timer_err tracks timeslice limit, the timeslice only resets
+     *   when pthread_cond_timedwait returns ETIMEDOUT, so frequent
+     *   switching between contended/uncontended GVL won't reset the
+     *   timer.
+     */
+    struct list_head waitq; /* <=> native_thread_data_t.node.ubf */
     const struct rb_thread_struct *timer;
     int timer_err;