thread_local_var_accessors 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 939ace98d853409e91249ccd6a34a1acfa707f77293984c9143e4acee3e011a1
-  data.tar.gz: bd876354d8cae177ee222d6fbe7110f417013485d568ce3bd031aa068c752883
+  metadata.gz: 4537e0db3960367d75a6ab4d731026c6a425e315816bf0523d078b563b90a09a
+  data.tar.gz: d270efc557c3b04f41ae9adf7850157d98c793a7d57cd025e8c88a40d2aaa154
 SHA512:
-  metadata.gz: 6a3c026cd82bf5676d412ae88a799645afa5e5f3c9a85b552489656a8c1a9340435dfbd8ab1e00c0400d28f4792c009bb7f19d100f7a6792d77be71fe7ba3a04
-  data.tar.gz: 72001afd55e3c86e9da161f8d596fb148dd33a009a33ca72cc126425a59f6e8238adab52f2360de4e14b29c037f44aa2c728e01456b8dc0c3f22253d242e5fc6
+  metadata.gz: b1ad3ff8ce74641cdb6956fe084d8bd69e2712b002805302c2ca3550d82591e2874e94322dbf3ba4123f70f8185318fb05c6ef51e8527ce6145361f72347fb64
+  data.tar.gz: 16ad94b606dfc4249bf344fcd859c1db7929bd026680fc8ef885e6768097c20cfbbc4753543c4989fea1095ce2876fbd525b5ba9090570fd117d79936446838b

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    thread_local_var_accessors (1.1.0)
+    thread_local_var_accessors (1.3.0)
       concurrent-ruby
 
 GEM

data/README.md

@@ -28,10 +28,10 @@ variables that use `ThreadLocalVar` (TLV) objects.
   the instance variable names '@name', which is expected to be either nil,
   or already have a `Concurrent::ThreadLocalVar` instance.
 
-- `tlv_writer` creates an instance method with the name `name=`, which accepts a single
-  argument that is the new value.  This method checks for an existing value
-  on the instance variable named `@name`, which should be a
-  `Concurrent::ThreadLocalVar` instance.  If `@name` value is nil, then a new
+- `tlv_writer` creates an instance method with the name `name=`, which accepts a
+  single argument that is the new value. This method checks for an existing
+  value on the instance variable named `@name`, which should be a
+  `Concurrent::ThreadLocalVar` instance. If `@name` value is nil, then a new
   `Concurrent::ThreadLocalVar` instance is assigned to it. In either case, the
   instance variable's TLV object is assigned the new value, which is returned.
 
@@ -41,25 +41,32 @@ 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.
+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 }
+    tlv_get NAME                    # => TLV value
+    tlv_set NAME, VALUE             # => TLV value
+    tlv_set NAME { VALUE }          # => TLV value
+    tlv_set_once NAME, VALUE        # => current TLV value, or new VALUE
+    tlv_set_once NAME { VALUE }     # => current TLV value, or new VALUE
 
-These methods manage the default values for thread-local variables:
+There is a method to fetch the TLV object for a given instance variable name,
+but only if it is actually a TLV.  If the instance variable is unassigned, or
+contains a non-TLV, then `nil` is returned.
 
-    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 }
+    tlv_get_var NAME                # => TLV object or nil
+
+The methods below manage the default values for thread-local variables:
+
+    tlv_new NAME, DEFAULT           # => new TLV
+    tlv_new NAME { DEFAULT }        # => new TLV
+    tlv_init NAME, DEFAULT          # => DEFAULT
+    tlv_init NAME { DEFAULT }       # => DEFAULT
+    tlv_default NAME                # => TLV default value for NAME
+    tlv_set_default NAME, VALUE     # => VALUE
+    tlv_set_default NAME { VALUE }  # => VALUE
 
 ### Instance Variable Details
 
@@ -86,20 +93,21 @@ 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.
+The TLV default value is used across *all* threads, when there is no value
+specifically assigned for a given thread.
 
     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.
+The `tlv_init` method is essentially the same as `tlv_set_default` followed
+by `tlv_get`: 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, 0)  # => 0
 
-    tlv_set(:timeout) # ensure that @timeout is initialized to an TLV
+    tlv_set(:timeout)     # @timeout = Concurrent::ThreadLocalVar.new
     @timeout.value = 0
 
 ### More Details
@@ -121,8 +129,8 @@ a TLV value only if has not currently be set already.
 
     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:
+For `tlv_accessor` instance variables, it's possible to use the assign operators, 
+eg: `+=`, or `||=`. For example:
 
     tlv_accessor :timeout, :count
 
@@ -152,14 +160,16 @@ Then:
 
 ## Usage
 
-To use the class methods, they must be included into the current module or class, with:
+To use the class methods, they must be included into the current module or
+class, with:
 
     class MyNewClass
       include ThreadLocalVarAccessors
         ...
     end
 
-With the include above, you can use the class methods to declare instance getter and setter methods:
+With the include above, you can use the class methods to declare instance getter
+and setter methods:
 
     class MyNewClass
       include ThreadLocalVarAccessors
@@ -175,11 +185,15 @@ The above invocations:
 - create reader methods for `name1`, `name3`, and `name4`.
 - create writer methods for `name2`, `name3`, and `name4`.
 
-The writer methods accept a value as the second argument, or from the result of an optional, associated block.
+The writer methods accept a value as the second argument, or from the result of
+an optional, associated block.
 
-Note: to use the read-and-operate operators, eg: `+=`, `-=`, `||=`, etc., the object must have both a reader and writer method.  In other words, it needs to have been created as an `tlv_accessor`.
+Note: to use the read-and-operate operators, eg: `+=`, `-=`, `||=`, etc., the
+object must have both a reader and writer method. In other words, it needs to
+have been created as an `tlv_accessor`.
 
-When adapting legacy code to become thread-safe, it's sometimes necessary to use the underlying instance methods:
+When adapting legacy code to become thread-safe, it's sometimes necessary to use
+the underlying instance methods:
 
     tlv_get(name)
     tlv_set(name, value)
@@ -192,7 +206,8 @@ Alternative block forms:
 
 In all cases, the `name` can be a string or symbol, with or without a leading `@`.
 
-Ultimately, these methods are all doing these basic accesses of the corresponding instance variables:
+Ultimately, these methods are all performing basic accesses of the corresponding
+instance variables:
 
     @name1 ||= ThreadLocalVar.new
     @name1.value = per_thread_value
@@ -222,7 +237,10 @@ class MyClass
     self.sleep_time = args[:sleep_time]
   end
   
-  # if the ivars might possibly be inherited in new threads after initialization
+  # if the ivars might possibly be inherited in new threads after 
+  # initialization, then the defaults should be set for each thread to
+  # inherit.
+          
   def alt_initialize(**args)
     # for each ivar, set the default value, which is inherited across all threads
     tlv_init :limit,      args[:limit]
@@ -246,9 +264,12 @@ end
 
 ## 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.
+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.
 
-For both development and testing, the environment variables described above must be defined.
+For both development and testing, the environment variables described above must
+be defined.
 
 ## Testing
 
@@ -256,11 +277,15 @@ For both development and testing, the environment variables described above must
 
 This repo is configured to the [gitflow](https://datasift.github.io/gitflow/IntroducingGitFlow.html) pattern, with the `develop` branch being the _default_ branch on PRs.
 
-The `main` branch gets updated with a PR or with a manual merge-and-push from the `develop` branch by a repo admin.
+The `main` branch gets updated with a PR or with a manual merge-and-push from
+the `develop` branch by a repo admin.
 
-When any branch is pushed, the continuous integration with causes the branch to be tested with all of the `rspec` tests _(except the integration tests)_.
+When any branch is pushed, the continuous integration with causes the branch to
+be tested with all of the `rspec` tests _(except the integration tests)_.
 
-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.
+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:
 

data/lib/thread_local_var_accessors/version.rb

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

data/lib/thread_local_var_accessors.rb

@@ -230,16 +230,34 @@ module ThreadLocalVarAccessors
   # instance methods
   # Returns the value of the TLV instance variable, if any.
   def tlv_get(name)
-    instance_variable_get(name.to_ivar)&.value
+    tlv_get_var(name)&.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
+  # @return [ThreadLocalVar] the TLV, if any, of the named instance variable.
+  def tlv_get_var(name)
+    var = instance_variable_get(name.to_ivar)
+    var if var.is_a?(Concurrent::ThreadLocalVar)
+  end
+
+  # If the instance variable is already a TLV, then set it's value to the
+  # given value, or the value returned by the block, if any.  If the
+  # instance variable is not a TLV, then create a new TLV, initializing
+  # it's default value with the given value, or the value returned by the block,
+  # if any, then, returning it's local value -- which returns the default value.
+  #
+  # This method is equivalent to:
+  #     if @name.is_a?(ThreadLocalVar)
+  #       @name.value = block_given? ? yield : value
+  #     else
+  #       @name = ThreadLocalVar(value, &block)
+  #     end
+  # @return [Object] the value of the TLV instance variable
   def tlv_set(name, value = nil, &block)
-    var = instance_variable_get(name.to_ivar) || tlv_new(name)
-    tlv_set_var(var, value, &block)
+    if (var = tlv_get_var(name))
+      tlv_set_var(var, value, &block)
+    else
+      tlv_new(name, value, &block).value
+    end
   end
 
   # Sets the thread-local value of the TLV instance variable, but only
@@ -247,12 +265,12 @@ module ThreadLocalVarAccessors
   #     @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 = tlv_get_var(name))&.value
       var.value
     elsif var # var is set, but its value is nil
       tlv_set_var(var, value, &block)
-    else # var is not set
-      tlv_set_var(tlv_new(name), value, &block)
+    else # var is not set, initialize it
+      tlv_new(name, value, &block).value
     end
   end
 
@@ -260,27 +278,38 @@ module ThreadLocalVarAccessors
   # 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))
+    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.
+  # Returns the value of the new TLVar.
   # Equivalent to:
   #     @name ||= ThreadLocalVar.new
   #     @name.instance_variable_set(:@default, block_given? ? yield : default)
+  #     @name.value
   def tlv_init(name, default=nil, &block)
     tlv_set_default(name, default, &block)
+    tlv_get(name)
   end
 
-  # Fetches the default value for the TLVar
-  # Equivalent to:
-  #     @name&.send(:default)
+  # Fetches the default value for the TLVar at the ivar
   def tlv_default(name)
-    instance_variable_get(name.to_ivar)&.send(:default)
+    tlv_get_default(tlv_get_var(name))
+  end
+
+  # gets the default value from a TLV
+  # this masks the private ThreadLocalVar#default method
+  def tlv_get_default(tlv)
+    tlv&.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.
+  # @return [Object] the effective default value of the TLV instance variable
   def tlv_set_default(name, default=nil, &block)1
     tlv = instance_variable_get(name.to_ivar)
     if tlv
@@ -295,8 +324,9 @@ module ThreadLocalVarAccessors
       end
       tlv
     else
-      tlv_new(name, default, &block)
+      tlv = tlv_new(name, default, &block)
     end
+    tlv_get_default(tlv)
   end
 
   # @!visibility private

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: thread_local_var_accessors
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Alan Stebbens
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-05-27 00:00:00.000000000 Z
+date: 2023-06-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler