thread_local_var_accessors 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44a2d47618384051b762c595994639af0699cde590462760853d3be02a611ffa
-  data.tar.gz: 4d4e3629f6bdfa482e5f080c6576d4a74d465a6b67c567b3c169db87e3b782fa
+  metadata.gz: 939ace98d853409e91249ccd6a34a1acfa707f77293984c9143e4acee3e011a1
+  data.tar.gz: bd876354d8cae177ee222d6fbe7110f417013485d568ce3bd031aa068c752883
 SHA512:
-  metadata.gz: e840c90fd9f096762ee4fd12ba5c4cffc9fb6952af177375327e04395cd9734a572542f1301ada916704daa507c21aaf42d4543d4dd01538e85bdf652a631c34
-  data.tar.gz: 826a2db9381d3f7ab70482b0c866427554e58e4c7d70e238964e34593437add0d276067a21aa2e2775f8b9dc050cf05e99776f56374f330dd2a9e952738ecda7
+  metadata.gz: 6a3c026cd82bf5676d412ae88a799645afa5e5f3c9a85b552489656a8c1a9340435dfbd8ab1e00c0400d28f4792c009bb7f19d100f7a6792d77be71fe7ba3a04
+  data.tar.gz: 72001afd55e3c86e9da161f8d596fb148dd33a009a33ca72cc126425a59f6e8238adab52f2360de4e14b29c037f44aa2c728e01456b8dc0c3f22253d242e5fc6

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    thread_local_var_accessors (1.0.0)
+    thread_local_var_accessors (1.1.0)
       concurrent-ruby
 
 GEM
@@ -9,6 +9,8 @@ GEM
   specs:
     ast (2.4.2)
     builder (3.2.4)
+    byebug (11.1.3)
+    coderay (1.1.3)
     concurrent-ruby (1.2.2)
     diff-lcs (1.5.0)
     docile (1.4.0)
@@ -16,9 +18,16 @@ GEM
       rspec-core (~> 3.0)
       ruby-progressbar (~> 1.4)
     json (2.6.3)
+    method_source (1.0.0)
     parallel (1.22.1)
     parser (3.2.1.1)
       ast (~> 2.4.1)
+    pry (0.14.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    pry-byebug (3.10.1)
+      byebug (~> 11.0)
+      pry (>= 0.13, < 0.15)
     rainbow (3.1.1)
     rake (13.0.6)
     redcarpet (3.6.0)
@@ -74,6 +83,7 @@ PLATFORMS
 DEPENDENCIES
   bundler
   fuubar
+  pry-byebug
   rake
   redcarpet
   rspec

data/README.md

@@ -41,6 +41,28 @@ For reference, see [ThreadLocalVars](https://ruby-concurrency.github.io/concurre
 
 ### Instance Methods
 
+The following are a brief list of the instance variable in the `ThreadLocalVarAccessors` class.
+
+These methods interrogate or set thread-local variable values:
+
+    tlv_get NAME
+    tlv_set NAME, VALUE
+    tlv_set NAME { VALUE }
+    tlv_set_once NAME, VALUE
+    tlv_set_once NAME { VALUE }
+
+These methods manage the default values for thread-local variables:
+
+    tlv_new NAME, DEFAULT
+    tlv_new NAME { DEFAULT }
+    tlv_init NAME, DEFAULT
+    tlv_init NAME { DEFAULT }
+    tlv_default NAME
+    tlv_set_default NAME, VALUE
+    tlv_set_default NAME { VALUE }
+
+### Instance Variable Details
+
 With the accessor methods, obtaining values and setting values
 becomes very simple:
 
@@ -49,16 +71,29 @@ becomes very simple:
     timeout  # fetches the current TLV value, unique to each thread
     ...
     self.timeout = 0.5  # stores the TLV value just for this thread
-    
+
 The `tlv_init` method creates a _new_ TLVar and sets its default value.
 
-Note that the default value is used when any thread evaluates the instance 
+Note that the default value is used when any thread evaluates the instance
 variable and there has been no thread-specific value assignment.
 
+Note: It's a best practice to use `tlv_init` to set the thread-local
+instance variables with non-nil defaults that may be inherited across multiple
+threads.
+
+On the other hand, if the ruby developer using threads does not rely on
+any particular value (other than nil) to be inherited, then using `tlv_set`
+is the right way to go.
+
+
 The TLV default value is used across *all* threads.
 
-    tlv_init(:timeout, _default_)
-    tlv_init(:timeout) { _default_ }
+    tlv_init(:timeout, default)
+    tlv_init(:timeout) { default }
+
+The `tlv_init` method is essentially the same as `tlv_set_default`: it sets the
+default value (or block) of a given TLVar, without affecting any possible
+thread-local variables already assigned.
 
 Alternative ways to initialize:
 
@@ -67,7 +102,9 @@ Alternative ways to initialize:
     tlv_set(:timeout) # ensure that @timeout is initialized to an TLV
     @timeout.value = 0
 
-The following methods are used within the above reader, writer, accessor
+### More Details
+
+The following methods are used within the above reader, writer, and accessor
 methods:
 
     tlv_get(name)        - fetches the value of TLV `name`
@@ -76,29 +113,29 @@ methods:
 There is a block form to `tls_set`:
 
     tlv_set(name) { |old_val| new_val }
-   
+
 In addition, there is also a `tlv_set_once` method that can be used to set
 a TLV value only if has not currently be set already.
 
     tlv_set_once(name, value)
-    
+
     tlv_set_once(name) { |old_val| new_value }
 
 For `tlv_accessor` instance variables, it's possible to use the assign operators, eg: `+=`, or `||=`.
 For example:
 
     tlv_accessor :timeout, :count
-    
+
     self.timeout ||= DEFAULT_TIMEOUT
-    
+
     self.count += 1
 
 ### TLV Name Arguments
 
 The `name` argument to `tlv_get` and `tlv_set` is the same as given on
 the accessor, reader, and writer methods: either a string or symbol name,
-automatically converted as needed to instance-variable syntax (eg: :@name),
-and setter-method name syntax (eg :name=).
+automatically converted as needed to instance-variable syntax (eg: `:@name`),
+and setter-method name syntax (eg `:name=`).
 
 
 ## Installation
@@ -121,7 +158,7 @@ To use the class methods, they must be included into the current module or class
       include ThreadLocalVarAccessors
         ...
     end
-    
+
 With the include above, you can use the class methods to declare instance getter and setter methods:
 
     class MyNewClass
@@ -130,10 +167,10 @@ With the include above, you can use the class methods to declare instance getter
       tlv_reader   :name1
       tlv_writer   :name2
       tlv_accessor :name3, :name4
-      
+
     end
-    
-The above invocations: 
+
+The above invocations:
 
 - create reader methods for `name1`, `name3`, and `name4`.
 - create writer methods for `name2`, `name3`, and `name4`.
@@ -147,7 +184,7 @@ When adapting legacy code to become thread-safe, it's sometimes necessary to use
     tlv_get(name)
     tlv_set(name, value)
     tlv_set_once(name, value)
-    
+
 Alternative block forms:
 
     tlv_set(name)      { |oldval| newval }
@@ -161,8 +198,8 @@ Ultimately, these methods are all doing these basic accesses of the correspondin
     @name1.value = per_thread_value
     ...
     @name1.value # returns the per_thread_value
-    
-If you prefer the style above, then you don't really need these accessor methods. 
+
+If you prefer the style above, then you don't really need these accessor methods.
 
 ### Example Usage
 
@@ -176,12 +213,23 @@ class MyClass
   tlv_reader   :sleep_time
   tlv_writer   :locked
 
+  # if the ivars will not be inherited in new threads after initialization
   def initialize(**args)
+    # set the current thread's local value for each ivar
     self.limit      = args[:limit]
     self.timeout    = args[:timeout]
     self.max_time   = args[:max_time]
     self.sleep_time = args[:sleep_time]
   end
+  
+  # if the ivars might possibly be inherited in new threads after initialization
+  def alt_initialize(**args)
+    # for each ivar, set the default value, which is inherited across all threads
+    tlv_init :limit,      args[:limit]
+    tlv_init :timeout,    args[:timeout]
+    tlv_init :max_time,   args[:max_time]
+    tlv_init :sleep_time, args[:sleep_time]
+  end
 
   def run
     while count < limit && delay_time < timeout
@@ -196,29 +244,6 @@ class MyClass
 end
 ```
 
-There may be times where you may want to use the `tlv_`-prefix methods and not use the accessors.
-
-The following are a set of equivalencies.
-
-```ruby
-    tlv_accessor :timeout
-```
-
-produces both the reader and writer methods, using the `tlv_get` and `tlv_set` methods.
-
-```ruby
-    def timeout
-      tlv_get(:timeout)
-    end
-
-    def timeout=(val)
-      tlv_set(:timeout, val)
-    end
-```
-
-The advantage of the block method, especially for `tlv_set_once`, is that the
-VALUE is only evaluated when the instance variable value is being set, and, the block will receive the old value as a parameter.
-
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -238,5 +263,5 @@ When any branch is pushed, the continuous integration with causes the branch to
 When the `main` branch is updated and after its tests pass, the `deploy` action is invoked which causes the newest build of the gem to be pushed to rubygems.org.
 
 ## Original Author:
-  
+
     Alan K. Stebbens <aks@stebbens.org>

data/lib/thread_local_var_accessors/version.rb

@@ -1,3 +1,3 @@
 module ThreadLocalVarAccessors
-  VERSION = '1.0.0'
+  VERSION = '1.1.0'
 end

data/lib/thread_local_var_accessors.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'concurrent-ruby'
+
 # This module has methods making it easy to use the Concurrent::ThreadLocalVar
 # as instance variables.  This makes instance variables using this code as
 # actually thread-local, without also leaking memory over time.
@@ -7,6 +9,8 @@
 # See [Why Concurrent::ThreadLocalVar](https://github.com/ruby-concurrency/concurrent-ruby/blob/master/lib/concurrent-ruby/concurrent/atomic/thread_local_var.rb#L10-L17)
 # to understand why we use TLVs instead of `Thread.current.thread_variable_(set|get)`
 #
+# Class Methods
+#
 # The following class methods declare `Concurrent::ThreadLocalVar` reader,
 # writer, and accessors with these class methods:
 #
@@ -32,58 +36,85 @@
 #
 #     tlv_accessor :timeout
 #
+# Instance Methods
+#
 # Create a new TLV instance with an associated default, applied across all threads.
 #
-#     tlv_init :timeout, default_timeout
+#     tlv_new :timeout, default_timeout
+#     tlv_new :timeout { default_timeout }
 #
-#     tlv_init :timeout { default_timeout }
+# This method _always_ assignes the instance variable.  It is equivalent to:
 #
+#     @instance_var = ThreadLocalVar.new(default)
+#     @instance_var = ThreadLocalVar.new { default }
+#
+# Assign the current thread value for the TLV variable:
+#
+#     self.timeout = 0.5  # stores the TLV value just for this thread
+#
+# which is equivalent to:
+#
+#     @timeout ||= ThreadLocalVar.new
+#     @timeout.value = 0.5
 #
 # Reference the current thread value for the TLV variable:
 #
 #     timeout  # fetches the current TLV value, unique to each thread
 #
-# Assign the current thread value for the TLV variable:
+# which is the same as:
 #
-#     self.timeout = 0.5  # stores the TLV value just for this thread
+#     @timeout ||= ThreadLocalVar.new
+#     @timeout.value
 #
 # Alternative ways to initialize the thread-local value:
 #
-#     ltv_set(:timeout, 0)
-#
-#     ltv_set(:timeout) # ensure that @timeout is initialized to an LTV
-#
-#     @timeout.value = 0
+#     tlv_set(:timeout, 0)
+#     tlv_set(:timeout) # ensure that @timeout is initialized to an LTV
+#     tlv_set_once(:timeout, value) # set timeout only if it isn't already set
 #
 # Each thread-local instance can be independently assigned a value, which defaults
 # to the _default_ value, or _block_, that was associated with the original
-# `ThreadLocalVar.new` method.  This module also provides an easy way to do this:
+# `ThreadLocalVar.new` method.  This module also provides an easy way to do this.
 #
 # Initializes a TLV on the `@timeout` instance variable with a default value of
 # 0.15 seconds:
 #
-#     tlv_init(:timeout, 0.15)
+#     tlv_new(:timeout, 0.15)
 #
 # This does the same, but uses a block (a Proc object) to possibly return a
 # dynamic default value, as the proc is invoked each time the TLV instance is
 # evaluted in a Thread.
 #
-#     tlv_init(:sleep_time) { computed_sleep_time }
+#     tlv_new(:sleep_time) { computed_sleep_time }
 #
 # The block-proc is evaluated at the time the default value is needed, not when
 # the TLV is assigned to the instance variable.  In other words, much later
 # during process, when the instance variable value is evaluated, _that_ is when
 # the default block is evaluated.
 #
+# The `tlv_new` method always assigns a new TLVar to the named instance variable.
+#
+# There is a corresponding method to either create a new TLVar instance or
+# assign the default value to the existing TLVar instance: `tlv_init`.
+#
+#     tlv_init(IVAR, DEFAULT)
+#     tlv_init(IVAR) { DEFAULT }
+#
 # Note that `tlv_init` does not assign the thread-local value; it assigns the
 # _instance variable_ to a new TLV with the given default.  If any thread
 # evaluates that instance variable, the default value will be returned unless
-# and until each thread associates a new, thread-local value with the TLV.
+# and until the current thread associates a new, thread-local value with the TLV
+# instance.
+#
+# The purpose of `tlv_init` is to make the initialization of a TLVar be idempotent:
+# a. if the TLVar does not yet exist, it is created with the default value.
+# b. if the TLVar already exists, it's default value is set.
+#
+# In neither case are any thread-local value set; only the default.
 #
 # The default for an existing TLV can be redefined, using either an optional
 # default value, or an optional default block.
 #
-#
 #     tlv_set_default(:timeout, new_default)
 #     tlv_set_default(:timeout) { new_default }
 #
@@ -145,10 +176,7 @@
 # To assign a new value to an TLV instance:
 #
 #     @timeout.value = new_value
-
-require 'concurrent-ruby'
-
-# methods for making usage of ThreadLocalVars easy
+#
 module ThreadLocalVarAccessors
   # @!visibility private
   module MyRefinements
@@ -200,17 +228,26 @@ module ThreadLocalVarAccessors
   end
 
   # instance methods
+  # Returns the value of the TLV instance variable, if any.
   def tlv_get(name)
     instance_variable_get(name.to_ivar)&.value
   end
 
+  # sets the thread-local value of the TLV instance variable, creating
+  # it if necessary. This method is equivalent to:
+  #     @name ||= ThreadLocalVar.new
+  #     @name.value = block_given? ? yield : value
   def tlv_set(name, value = nil, &block)
     var = instance_variable_get(name.to_ivar) || tlv_new(name)
     tlv_set_var(var, value, &block)
   end
 
+  # Sets the thread-local value of the TLV instance variable, but only
+  # if it is not already set.  It is equivalent to:
+  #     @name ||= ThreadLocalVar.new
+  #     @name.value ||= block_given? yield : value
   def tlv_set_once(name, value = nil, &block)
-    if (var = instance_variable_get(name.to_ivar)) && !var.value.nil?
+    if (var = instance_variable_get(name.to_ivar)) && !var&.value.nil?
       var.value
     elsif var # var is set, but its value is nil
       tlv_set_var(var, value, &block)
@@ -219,26 +256,32 @@ module ThreadLocalVarAccessors
     end
   end
 
-  # @param [String|Symbol] name the TLV name
-  # @param [Object|nil] default the optional default value
-  # @param [Proc] block the optional associated block
-  # @return [ThreadLocalVar] a new TLV set in the instance variable
-  # @example Default argument
-  #   tlv_init(:ivar, default_value)
-  # @example Default block
-  #   tlv_init(:ivar) { default_value }
-  def tlv_init(name, default=nil, &block)
+  # Creates a new TLVar with the given default value or block.
+  # Equivalent to:
+  #     @name = ThreadLocalVar.new(block_given? ? yield : default)
+  def tlv_new(name, default=nil, &block)
     instance_variable_set(name.to_ivar, Concurrent::ThreadLocalVar.new(default, &block))
   end
-  alias tlv_new tlv_init
+
+  # Creates a new TLVar with a default, or assigns the default value to an
+  # existing TLVar, without affecting any existing thread-local values.
+  # Equivalent to:
+  #     @name ||= ThreadLocalVar.new
+  #     @name.instance_variable_set(:@default, block_given? ? yield : default)
+  def tlv_init(name, default=nil, &block)
+    tlv_set_default(name, default, &block)
+  end
 
   # Fetches the default value for the TLVar
+  # Equivalent to:
+  #     @name&.send(:default)
   def tlv_default(name)
     instance_variable_get(name.to_ivar)&.send(:default)
   end
 
-  # Sets the default value or block for the TLV _(which is applied across all threads)_
-  def tlv_set_default(name, default=nil, &block)
+  # Sets the default value or block for the TLV _(which is applied across all threads)_.
+  # Creates a new TLV if the instance variable is not initialized.
+  def tlv_set_default(name, default=nil, &block)1
     tlv = instance_variable_get(name.to_ivar)
     if tlv
       raise ArgumentError, "tlv_set_default: can only use a default or a block, not both" if default && block
@@ -250,8 +293,9 @@ module ThreadLocalVarAccessors
         tlv.instance_variable_set(:@default_block, nil)
         tlv.instance_variable_set(:@default, default)
       end
+      tlv
     else
-      tlv_init(name, default, &block)
+      tlv_new(name, default, &block)
     end
   end
 

data/thread_local_var_accessors.gemspec

@@ -19,6 +19,7 @@ Gem::Specification.new do |s|
 
   s.add_development_dependency 'bundler'
   s.add_development_dependency 'fuubar'
+  s.add_development_dependency 'pry-byebug'
   s.add_development_dependency 'rake'
   s.add_development_dependency 'redcarpet'
   s.add_development_dependency 'rspec'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: thread_local_var_accessors
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Alan Stebbens
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-05-26 00:00:00.000000000 Z
+date: 2023-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -38,6 +38,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement