User Guide chapter for address-based hashing (#1294)

This PR adds a User Guide chapter for address-based hashing.

We also extended the Glossary to introduce GC-safe points and related
concepts.

Author: wks

docs/userguide/src/SUMMARY.md

@@ -40,6 +40,7 @@
         - [Optimizing Allocation](portingguide/perf_tuning/alloc.md)
     - [VM-specific Concerns](portingguide/concerns/prefix.md)
         - [Finalizers and Weak References](portingguide/concerns/weakref.md)
+        - [Address-based Hashing](portingguide/concerns/address-based-hashing.md)
 - [API Migration Guide](migration/prefix.md)
     - [Template (for mmtk-core developers)](migration/template.md)
 

docs/userguide/src/glossary.md

@@ -16,18 +16,19 @@ conventional graphs, an edge may originate from either another node or a *root*.
 Each *node* represents an object in the heap.
 
 Each *edge* represents an object reference from an object or a root.  A *root* is a reference held
-in a slot directly accessible from [mutators][mutator], including local variables, global variables,
+in a slot directly accessible from [mutators], including local variables, global variables,
 thread-local variables, and so on.  A object can have many fields, and some fields may hold
 references to objects, while others hold non-reference values.
 
 An object is *reachable* if there is a path in the object graph from any root to the node of the
-object.  Unreachable objects cannot be accessed by [mutators][mutator].  They are considered
+object.  Unreachable objects cannot be accessed by [mutators].  They are considered
 garbage, and can be reclaimed by the garbage collector.
 
-[mutator]: #mutator
-
 ## Mutator
 
+[mutator]: #mutator
+[mutators]: #mutator
+
 TODO
 
 ## Emergency Collection
@@ -47,6 +48,153 @@ implementing memory-sensitive caches.
 
 [java-soft-ref]: https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/ref/SoftReference.html
 
+## GC-safe Point
+
+[GC-safe point]: #gc-safe-point
+[GC-safe points]: #gc-safe-point
+
+Also known as: *GC-point*
+
+A *GC-safe point* is a place in the code executed by mutators where (stop-the-world) garbage
+collection is allowed to happen.  Concurrent GC can run concurrently with mutators, but still needs
+to synchronize with mutators at GC-safe points.  Regardless, the following statements must be true
+when a mutator is at a GC-safe point.
+
+-   References held by a mutator can be identified.  That include references in local variables,
+    thread-local variables, and so on.  For compiled code, that include those in stack slots and
+    machine registers.
+-   The mutator cannot be in the middle of operations that must be *atomic with respect to GC*.
+    That includes [write barriers], [address-based hashing], etc.
+
+### Code With GC Semantics
+
+Compilers (including ahead-of-time and just-in-time compilers) for programs with garbage collection
+semantics (such as Java source code or bytecode) usually understand GC semantics, too, and can
+generate [yieldpoints] and [stack maps] to assist GC.
+
+In practice, such compilers only make certain places in a function GC-safe and only generate [stack
+maps] at those places, including but not limited to:
+
+-   [yieldpoints]
+-   object allocation sites (may trigger GC)
+-   call sites to other functions where GC is allowed to happen inside
+
+If we allow GC to happen at arbitrary PC, it will either force the compiler to generate [stack maps]
+at all PCs, or force the VM to use [shadow stacks] or [conservative stack scanning], instead.  It
+will also break operations that must be *atomic with respect to GC*, such as [write barrier] and
+[address-based hashing].
+
+### Code Without GC Semantics
+
+In contrast, for programs without GC semantics (e.g. programs written in C, C++, Rust, etc.), their
+compilers (GCC, clang, rustc, ...) are agnostic to GC.  But many VMs (such as OpenJDK, CRuby, Julia,
+etc.) are implemented in such languages.  We don't usually use the term "GC-safe point" for
+functions written in C, C++, Rust, etc., but each VM has its own rules to determine whether GC can
+happen within functions written in those languages.
+
+Interpreters usually maintain local variables in dedicated stacks or frames data structures.
+References in such structures are identified by traversing those stacks or frames, and GC is usually
+allowed between bytecode instructions.
+
+Some runtime functions implement operations tightly related to GC, and must be *atomic w.r.t. GC*.
+For example, if a function initializes the type information in the header of an object, GC cannot
+happen in the middle.  Otherwise the GC will read a corrupted header and crash.  Other examples
+include functions that implement the write barrier [slow path] and [address-based hashing].  Such
+functions cannot allocate objects, and cannot call any function that may trigger GC.
+
+Some functions do not access the GC heap, or only access the heap in controlled ways (e.g. utilizing
+[object pinning], or via safe APIs such as [JNI]).  Some of such functions (such as wrappers for
+blocking system calls including `read` and `write`) are long-running.  GC is usually safe when some
+mutators are executing such functions.  Compilers for languages with GC semantics usually make *call
+sites* to such functions [GC-safe points], and generate [stack maps] at those call sites.  The
+runtime usually transitions the state of the current mutator thread so that the GC knows it is in
+such a function when requesting all mutators to stop at their next GC-safe points.
+
+[JNI]: https://docs.oracle.com/en/java/javase/21/docs/specs/jni/index.html
+
+## Stack Map
+
+[stack map]: #stack-map
+[stack maps]: #stack-map
+
+A *stack map* is a data structure that identifies stack slots and registers that may contain
+references.  Stack maps are essential for supporting [precise stack scanning].
+
+## Yieldpoint
+
+[yieldpoint]: #yieldpoint
+[yieldpoints]: #yieldpoint
+
+Also known as: *GC-check point*
+
+A *yieldpoint* is a point in a program where a mutator thread checks if it should yield from normal
+execution in order to handle certain events, such as garbage collection, profiling, biased lock
+revocation, etc.
+
+Compilers of programs with GC semantics (e.g. Java source code and byte code) insert yieldpoints in
+various places, such as function epilogues and loop back-edges.  In this way, when GC is triggered
+asynchronously by other threads, the current mutator can reach the next yieldpoint quickly and yield
+for GC promptly.  Compilers also generate [stack maps] at yieldpoints to make them [GC-safe points].
+
+Because some operations (such as [write barrier]) must be *atomic w.r.t. GC*, [yieldpoints] must not
+be inserted in the middle of such operations.
+
+Read the paper [*Stop and go: Understanding yieldpoint behavior*][LWB+15] by Lin et al. for more
+details.
+
+[LWB+15]: https://dl.acm.org/doi/10.1145/2754169.2754187
+
+## Address-based Hashing
+
+[address-based hashing]: #address-based-hashing
+
+*Address-based hashing* is a GC-assisted space-efficient high-performance method for implementing
+identity hash code in copying GC.
+
+Read the [Address-based Hashing](portingguide/concerns/address-based-hashing.md) chapter for more
+details.
+
+## Precise Stack Scanning
+
+[precise stack scanning]: #precise-stack-scanning
+
+Also known as: *exact stack scanning*
+
+TODO
+
+## Conservative Stack Scanning
+
+[conservative stack scanning]: #conservative-stack-scanning
+
+TODO
+
+## Shadow Stack
+
+[shadow stack]: #shadow-stack
+[shadow stacks]: #shadow-stack
+
+TODO
+
+## Write Barrier
+
+[write barrier]: #write-barrier
+[write barriers]: #write-barrier
+
+TODO
+
+## Fast Path and Slow Path
+
+[fast path]: #fast-path-and-slow-path
+[slow path]: #fast-path-and-slow-path
+
+TODO
+
+## Object Pinning
+
+[object pinning]: #object-pinning
+
+TODO
+
 <!--
 vim: tw=100 ts=4 sw=4 sts=4 et
 -->