[DOC] WIP concurrency guide

Author: luke-gruber

doc/concurrency_guide.md

@@ -0,0 +1,66 @@
+# Concurrency Guide
+
+This is a guide to thinking about concurrency in the native cruby source code, whether that's
+contributing to Ruby by writing C or Rust. This doesn't touch on native extensions, only the core
+language. It will go over:
+
+* How to use the VM lock, and what you can and can't do when you've acquired this lock.
+* What you can and can't do when you've acquired other native locks.
+* The difference between the VM lock and the GVL.
+* How to write code that is ractor safe.
+* What a VM barrier is and when to use it.
+* The lock hierarchy of some important locks.
+* How ruby interrupt handling works.
+* What happens when IO is performed through ruby.
+* The timer thread and what it's responsible for.
+
+
+## The VM Lock
+
+There's only one VM lock and its for critical sections that can only be entered by one ractor at a time.
+Without ractors, the VM lock is useless. It does not stop all ractors from running, as ractors can run
+without trying to acquire this lock. If you're updating global (shared) data between ractors and aren't using
+atomics, you need to use this lock. When you take the VM lock, there are things you can and can't do during
+your (hopefully brief) critical section:
+
+You can (as long as no other locks are also held):
+
+* Create ruby objects, call ruby_xmalloc, etc.
+
+* Raise exceptions or use `EC_JUMP_TAG`. The lock will automatically be unlocked depending on how far up the call stack you locked it, and how far you're jumping to.
+
+* Check ruby interrupts. Since raising exceptions can pop ruby frames and popping ruby frames checks interrupts, you are allowed.
+
+You can't:
+
+* Context switch to another thread or ractor. This is important, as many things can cause context switches including:
+
+    * Calling any ruby method through, for example, `rb_funcall`. If you execute ruby code with the VM lock, a context switch
+    could happen. This also applies to ruby methods defined in C. You also can't check if objects respond to methods or set
+    constants (these can both call ruby methods).
+
+    * Calling `rb_nogvl`
+
+    * Enter any blocking operation managed by ruby. This will context switch to another ruby thread.
+
+    * Calling a ruby-level mechanism that can context switch, like `rb_mutex_lock`.
+
+Internally, this is the `vm->ractor.sync.lock`.
+
+## 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 examples are the `interrupt_lock` and the ractor scheduling lock.
+
+You can't:
+
+* Raise exceptions or use `EC_JUMP_TAG` if it jumps out of the critical section.
+
+* Context switch. See the `VM Lock` section for more info.
+
+* Check interrupts. Doing so can raise exceptions or context switch.
+
+* Allocate memory through ruby. This includes creating ruby objects or using `ruby_xmalloc` or `st_insert`.
+
+
+