thread_local_var_accessors 0.1.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f567c363dc63194dc30aeae5d661ea14c871f9f64cc65ed3d2c2947447d1fc91
-  data.tar.gz: 30c3bc0763221a483de2370af6843c83b39ff6429f27f1b6ad796931fa9dae51
+  metadata.gz: 939ace98d853409e91249ccd6a34a1acfa707f77293984c9143e4acee3e011a1
+  data.tar.gz: bd876354d8cae177ee222d6fbe7110f417013485d568ce3bd031aa068c752883
 SHA512:
-  metadata.gz: 59329574532e6730a71d3f44d011bedae930ee29a0b592f9ff8fbf7ed6d824a13cb65ab9f51edb40df372615c5975f459bd483fc467f5914af48f992a21f7cfc
-  data.tar.gz: 822c3f467f172562efdab7a38cc73063b42b8937f09d71ad01345c52d80fa69bc438a60067756386aa8d4d8ba74055513cd4303875a3784b13a5d07e3120adcc
+  metadata.gz: 6a3c026cd82bf5676d412ae88a799645afa5e5f3c9a85b552489656a8c1a9340435dfbd8ab1e00c0400d28f4792c009bb7f19d100f7a6792d77be71fe7ba3a04
+  data.tar.gz: 72001afd55e3c86e9da161f8d596fb148dd33a009a33ca72cc126425a59f6e8238adab52f2360de4e14b29c037f44aa2c728e01456b8dc0c3f22253d242e5fc6

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+2023-05-04: Version 1.0.0
+- added support for default values:
+  - renamed `tlv_new` to `tlv_init` (leaving `tlv_new` as an alias)
+  - added new instance methods: `tlv_default`, `tlv_set_default`
+  - updated docs to explain how defaults are cross-threads
+- updated the README.md

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    thread_local_var_accessors (0.1.2)
+    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
@@ -87,4 +97,4 @@ DEPENDENCIES
   yard
 
 BUNDLED WITH
-   2.4.6
+   2.4.12

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:
 
@@ -50,14 +72,39 @@ becomes very simple:
     ...
     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
+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 }
+
+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:
 
     tlv_set(:timeout, 0)
 
-    tlv_set(:timeout) # ensure that @timeout is initialized to an [TLV](TLV)
+    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`
@@ -66,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
@@ -111,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
@@ -120,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`.
@@ -137,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 }
@@ -151,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
 
@@ -166,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
@@ -186,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.
@@ -228,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 = '0.1.2'
+  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:
 #
@@ -31,17 +35,93 @@
 # becomes very simple:
 #
 #     tlv_accessor :timeout
-#     ...
-#     timeout  # fetches the current TLV value, unique to each thread
-#     ...
+#
+# Instance Methods
+#
+# Create a new TLV instance with an associated default, applied across all threads.
+#
+#     tlv_new :timeout, default_timeout
+#     tlv_new :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
 #
-# Alternative ways to initialize:
+# 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
+#
+# which is the same as:
+#
+#     @timeout ||= ThreadLocalVar.new
+#     @timeout.value
+#
+# Alternative ways to initialize the thread-local value:
+#
+#     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.
+#
+# Initializes a TLV on the `@timeout` instance variable with a default value of
+# 0.15 seconds:
+#
+#     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.
 #
-#     ltv_set(:timeout, 0)
+#     tlv_new(:sleep_time) { computed_sleep_time }
 #
-#     ltv_set(:timeout) # ensure that @timeout is initialized to an LTV
-#     @timeout.value = 0
+# 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 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 }
+#
+# The default for an existing TLV can also be obtained, independently of the
+# current thread's local value, if any:
+#
+#     tlv_default(:timeout)
 #
 # The following methods are used within the above reader, writer, accessor
 # methods:
@@ -86,7 +166,8 @@
 #
 # Each thread referencing the instance variable, will get the same TLV object,
 # but when the `.value` method is invoked, each thread will receive the initial
-# value, or whatever local value may have been assigned subsequently.
+# value, or whatever local value may have been assigned subsequently, or the
+# default, which is the same across all the threads.
 #
 # To obtain the value of such an TLV instance variable, do:
 #
@@ -95,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
@@ -150,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)
@@ -169,10 +256,47 @@ module ThreadLocalVarAccessors
     end
   end
 
-  # @param [String|Symbol] name the TLV name
-  # @return [ThreadLocalVar] a new TLV set in the instance variable
-  def tlv_new(name)
-    instance_variable_set(name.to_ivar, Concurrent::ThreadLocalVar.new)
+  # 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
+
+  # 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)_.
+  # 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
+
+      if block
+        tlv.instance_variable_set(:@default_block, block)
+        tlv.instance_variable_set(:@default, nil)
+      else
+        tlv.instance_variable_set(:@default_block, nil)
+        tlv.instance_variable_set(:@default, default)
+      end
+      tlv
+    else
+      tlv_new(name, default, &block)
+    end
   end
 
   # @!visibility private

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: 0.1.2
+  version: 1.1.0
 platform: ruby
 authors:
 - Alan Stebbens
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-04-05 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
@@ -199,6 +213,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - Gemfile
 - Gemfile.lock
 - LICENSE