tmp commit

Author: luke-gruber

doc/concurrency_guide.md

@@ -45,11 +45,16 @@ You can't:
 
 Internally, the VM lock is the `vm->ractor.sync.lock`.
 
+You need to be on a ruby thread to take the VM lock. You also can't take it inside any functions that could be called during sweeping, as MMTK sweeps
+on another thread and you need a valid `ec` to grab the lock. For this same reason (among others), you can't take it from the timer thread either.
+
 ## Other Locks
 
 All native locks that aren't the VM lock share a more strict set of rules for what's allowed during the critical section. By native locks, we mean
-anything that uses `rb_native_mutex_lock`. Some important locks include the `interrupt_lock`, the ractor scheduling lock (global), the thread
-scheduling lock (local to each ractor) and the ractor lock (local to each ractor).
+anything that uses `rb_native_mutex_lock`. Some important locks include the `interrupt_lock`, the ractor scheduling lock (global, protects global scheduling data structures),
+the thread scheduling lock (local to each ractor, protects per-ractor scheduling data structures) and the ractor lock (local to each ractor, protects ractor data structures).
+
+When you acquire one of these locks,
 
 You can:
 
@@ -58,7 +63,7 @@ ruby allocation through the use of macros!
 
 * Use `ccan` lists, as they don't allocate.
 
-* Do the usual things like set variables or struct fields, manipulate linked lists, etc.
+* Do the usual things like set variables or struct fields, manipulate linked lists, signal condition variables etc.
 
 You can't:
 
@@ -97,3 +102,7 @@ know about and is sometimes the only solution.
 
 ## Lock Hierarchy
 
+## Ruby Interrupt Handling
+
+When the VM runs ruby code, ruby's threads intermittently check ruby-level interrupts. These software interrupts
+are for various things, like