From 2d42fe7fb5279e0dc3b1ff0831cb1c4fe1811de9 Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Sat, 13 Apr 2013 08:15:11 +0200 Subject: complete rewrite of the documentation of AS::PerThreadRegistry * It focuses on how to use it. * Removes some ambigueties in the original docs about whether the state is stored in the class. * Documents it provides class-level accessors via method_missing. * Documents that if the extended class has an initializer, it must accept no arguments. --- .../lib/active_support/per_thread_registry.rb | 45 ++++++++++++---------- 1 file changed, 24 insertions(+), 21 deletions(-) (limited to 'activesupport') diff --git a/activesupport/lib/active_support/per_thread_registry.rb b/activesupport/lib/active_support/per_thread_registry.rb index fb9a4c0e33..926df8b4cf 100644 --- a/activesupport/lib/active_support/per_thread_registry.rb +++ b/activesupport/lib/active_support/per_thread_registry.rb @@ -1,32 +1,35 @@ module ActiveSupport - # This module creates a local registry class inside each thread. It provides - # basic methods which will store thread locals in a single class. This - # prevents the proliferation of too many thread locals and allows you to - # explicitly keep track of each of the variables you're using as thread - # locals in a class which includes this module. + # This module is used to encapsulate access to thread local variables. # - # For example, instead of using a bunch of different thread locals to keep - # track of some variables like so: + # Given # - # Thread.current[:active_record_connection_handler] = connection_handler - # Thread.current[:active_record_sql_runtime] = sql_runtime + # module ActiveRecord + # class RuntimeRegistry + # extend ActiveSupport::PerThreadRegistry # - # You could use the following class which implements the +PerThreadRegistry+ - # module: + # attr_accessor :connection_handler + # end + # end # - # class NewRegistry - # extend ActiveSupport::PerThreadRegistry + # ActiveRecord::RuntimeRegistry gets an +instance+ class method + # that returns an instance of the class unique to the current thread. Thus, + # instead of polluting +Thread.current+ # - # attr_accessor :connection_handler, :sql_runtime - # end + # Thread.current[:connection_handler] + # + # you write + # + # ActiveRecord::RuntimeRegistry.instance.connection_handler + # + # A +method_missing+ handler that proxies to the thread local instance is + # installed in the extended class so the call above can be shortened to + # + # ActiveRecord::RuntimeRegistry.connection_handler # - # NewRegistry.instance.connection_handler = connection_handler - # NewRegistry.instance.sql_runtime = sql_runtime + # The instance is stored as a thread local keyed by the name of the class, + # that is the string "ActiveRecord::RuntimeRegistry" in the example above. # - # The new way of keeping track of the thread locals will create a new local - # inside of +Thread.current+ with a key which is the name of the extended - # class. Now you can easily access per thread variables by just calling the - # variable name on the registry. + # If the class has an initializer, it must accept no arguments. module PerThreadRegistry def instance Thread.current[self.name] ||= new -- cgit v1.2.3