DOCSP-44703: thread local variable getter/setter

snooty.toml

@@ -13,7 +13,7 @@ toc_landing_pages = [
     "/quick-start-rails",
     "/quick-start-sinatra",
     "/interact-data/specify-query",
-    "/issues-and-help"
+    "/issues-and-help",
 ]
 
 [constants]
@@ -31,5 +31,6 @@ server-manual = "Server manual"
 api = "https://www.mongodb.com/docs/mongoid/current/api"
 ruby-api = "https://www.mongodb.com/docs/ruby-driver/current/api"
 active-record-docs = "https://guides.rubyonrails.org"
+ruby-lang-api = "https://docs.ruby-lang.org/en/3.4"
 shared-library = "Automatic Encryption Shared Library"
 mdb-server = "MongoDB Server"

source/data-modeling/callbacks.txt

@@ -162,6 +162,25 @@ instance:
    :emphasize-lines: 6, 10-15
    :dedent:
 
+.. _mongoid-callbacks-thread-local-vars:
+
+Thread-Local Variables
+~~~~~~~~~~~~~~~~~~~~~~
+
+If you have embedded child documents in an association that has
+``cascade_callbacks: true`` configured, then the embedded child
+callbacks are executed within a {+language+} `Fiber
+<{+ruby-lang-api+}/Fiber.html>`__. This means that if you are using the
+``Thread#[]`` and ``Thread#[]=`` methods to get and set fiber-local
+variables, those callbacks are not reading or setting the values you expect.
+
+We recommended that you use the ``Thread#thread_variable_get`` and
+``Thread#thread_variable_set`` methods to get and set true
+thread-local variables. For convenience, {+odm+} v9.0.3 introduces
+the `Mongoid::Threaded.get <{+api+}/Mongoid/Threaded.html#get-instance_method>`__
+and `Mongoid::Threaded.set <{+api+}/Mongoid/Threaded.html#set-instance_method>`__
+methods to implement this functionality.
+
 Additional Information
 ----------------------
 

source/whats-new.txt

@@ -178,6 +178,17 @@ Removal of Deprecated Functionality
 - The deprecated class ``{+odm+}::Errors::InvalidStorageParent`` has
   been removed.
 
+Get and Set Thread-Local Variables
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 9.0.3
+
+You can use the `Mongoid::Threaded.get <{+api+}/Mongoid/Threaded.html#get-instance_method>`__
+and `Mongoid::Threaded.set <{+api+}/Mongoid/Threaded.html#set-instance_method>`__
+methods to query and modify thread-local variables. To learn when to use
+these methods, see the :ref:`mongoid-callbacks-thread-local-vars`
+section of the Callbacks guide.
+
 Index Verification Configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~