[pypy-commit] stmgc c7-refactor: Comments about v_nursery_section_end

[arigo]

Author: Armin Rigo <arigo at tunes.org>
Branch: c7-refactor
Changeset: r767:94ed263ba9d2
Date: 2014-02-18 15:42 +0100
http://bitbucket.org/pypy/stmgc/changeset/94ed263ba9d2/

Log:	Comments about v_nursery_section_end

diff --git a/c7/stm/nursery.h b/c7/stm/nursery.h
--- a/c7/stm/nursery.h
+++ b/c7/stm/nursery.h
@@ -3,5 +3,30 @@
 #define NSE_SIGNAL        1
 #define NSE_SIGNAL_DONE   2
 
+/* Rules for 'v_nursery_section_end':
+
+   - Its main purpose is to be read by the owning thread in stm_allocate().
+
+   - The owning thread can change its value without acquiring the mutex,
+     but it must do so carefully, with a compare_and_swap.
+
+   - If a different thread has the mutex, it can force the field to the
+     value NSE_SIGNAL or NSE_SIGNAL_DONE with a regular write.  This should
+     not be hidden by the compare_and_swap done by the owning thread:
+     even if it occurs just before or just after a compare_and_swap,
+     the end result is that the special value NSE_SIGNAL(_DONE) is still
+     in the field.
+
+   - When the owning thread sees NSE_SIGNAL, it must signal and wait until
+     the other thread restores the value to NSE_SIGNAL_DONE.  When the
+     owning thread sees NSE_SIGNAL_DONE, it can replace it, again with
+     compare_and_swap, with the real value.
+
+   - This should in theory be a volatile field, because it can be read
+     from stm_allocate() while at the same time being changed to the value
+     NSE_SIGNAL by another thread.  In practice, making it volatile has
+     probably just a small negative impact on performance for no good reason.
+*/
+
 static void align_nursery_at_transaction_start(void);
 static void restore_nursery_section_end(uintptr_t prev_value);
diff --git a/c7/stmgc.h b/c7/stmgc.h
--- a/c7/stmgc.h
+++ b/c7/stmgc.h
@@ -62,7 +62,7 @@
     int segment_num;
     char *segment_base;
     stm_char *nursery_current;
-    volatile uintptr_t v_nursery_section_end;  /* see nursery.h */
+    uintptr_t v_nursery_section_end;  /* see nursery.h */
     struct stm_thread_local_s *running_thread;
     stm_jmpbuf_t *jmpbuf_ptr;
 };