thread_local_var_accessors 1.1.0 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 939ace98d853409e91249ccd6a34a1acfa707f77293984c9143e4acee3e011a1
-  data.tar.gz: bd876354d8cae177ee222d6fbe7110f417013485d568ce3bd031aa068c752883
+  metadata.gz: 6ed08c93f6e727f6ba7dc57984a05669fbf06bfe99f4fd46b3a6e81f72727128
+  data.tar.gz: b8223cf233fa40fc0749849117c0b6773b2a9723fd98dd80aed9017275f9882f
 SHA512:
-  metadata.gz: 6a3c026cd82bf5676d412ae88a799645afa5e5f3c9a85b552489656a8c1a9340435dfbd8ab1e00c0400d28f4792c009bb7f19d100f7a6792d77be71fe7ba3a04
-  data.tar.gz: 72001afd55e3c86e9da161f8d596fb148dd33a009a33ca72cc126425a59f6e8238adab52f2360de4e14b29c037f44aa2c728e01456b8dc0c3f22253d242e5fc6
+  metadata.gz: d2387dc90dd67a904b4757a5461ecff8ca4c6b5cbd4ae515f3be15241df0a7e956583b6760ba6b7f6398fdcbdfcd64852f06c62579ea01edba2d3ae0763c670a
+  data.tar.gz: 1942812b37021fdeb8f4f4cf1acf782591e400c229247815f1308553ab37872caca9131aca67b304b1f5fcc3c43238699794ffae431ab19d236827913b6271c1

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+2024-05-09: Version 1.3.1
+- DRYed up the `tlv_default` method
+- Changed CI to support "release" task on the main branch
+- Added more tasks to the Rakefile
+- Added RELEASES to the version file.
+- Updated the ruby version to 3.1
+
 2023-05-04: Version 1.0.0
 - added support for default values:
   - renamed `tlv_new` to `tlv_init` (leaving `tlv_new` as an alias)

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    thread_local_var_accessors (1.1.0)
+    thread_local_var_accessors (1.3.1)
       concurrent-ruby
 
 GEM
@@ -79,6 +79,7 @@ GEM
 
 PLATFORMS
   x86_64-darwin-21
+  x86_64-linux
 
 DEPENDENCIES
   bundler

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/Rakefile

@@ -1,19 +1,37 @@
 # Rakefile for thread_local_var_accessors
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 require 'yard'
 
+namespace :spec do
+  desc 'run tests with code coverage'
+  task :coverage do
+    sh 'COVERAGE=1 bundle exec rake spec'
+  end
+end
+
+task build:   %i[bundle:add_linux]
+task install: %i[build spec]
+task release: %i[build spec]
+
 # Local CI testing
 
 namespace :ci do
-  desc "Check CIRCLECI config"
+  desc 'Check CIRCLECI config'
   task :check do
-    sh "circleci config validate", verbose: true
+    sh 'circleci config validate', verbose: true
   end
 
-  desc "Run CIRCLECI config locally"
+  desc 'Run CIRCLECI config locally'
   task :local do
-    sh "circleci local execute", verbose: true
+    sh 'circleci local execute', verbose: true
+  end
+end
+
+namespace :bundle do
+  desc 'add linux platform to Gemfile.lock'
+  task :add_linux do
+    sh "grep -s 'x86_64-linux' Gemfile.lock >/dev/null || bundle lock --add-platform x86_64-linux"
   end
 end
 
@@ -22,7 +40,7 @@ end
 RSpec::Core::RakeTask.new(:spec)
 
 namespace :spec do
-  desc "run Simplecov"
+  desc 'run Simplecov'
   task :coverage do
     sh 'CODE_COVERAGE=1 bundle exec rake spec'
   end

data/lib/thread_local_var_accessors/version.rb

@@ -1,3 +1,8 @@
 module ThreadLocalVarAccessors
-  VERSION = '1.1.0'
+  RELEASES = [
+    ['1.3.1', '2024-05-09'],
+    ['1.3.0', '2023-05-04']
+  ].freeze
+
+  VERSION = RELEASES[0][0]
 end

data/lib/thread_local_var_accessors.rb

@@ -160,7 +160,7 @@ require 'concurrent-ruby'
 #
 #     def timeout=(value)
 #       var = instance_variable_get(:@timeout) ||
-#             instance_variable_get(:@timeout, Concurrent::ThreadLocalVar.new)
+#             instance_variable_set(:@timeout, Concurrent::ThreadLocalVar.new)
 #       var.value = block_given? ? yield(var.value) : value
 #     end
 #
@@ -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,56 +265,66 @@ 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
 
   # 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))
+  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.
+  # Returns the value of the new TLVar.
   # Equivalent to:
   #     @name ||= ThreadLocalVar.new
   #     @name.instance_variable_set(:@default, block_given? ? yield : default)
-  def tlv_init(name, default=nil, &block)
+  #     @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.
-  def tlv_set_default(name, default=nil, &block)1
+  # @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
-      raise ArgumentError, "tlv_set_default: can only use a default or a block, not both" if default && block
+      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
+      # in both cases, the default is set to the given value, only one of which
+      # can be given at a time.
+      tlv.instance_variable_set(:@default_block, block)
+      tlv.instance_variable_set(:@default, default)
       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.1
 platform: ruby
 authors:
 - Alan Stebbens
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-05-27 00:00:00.000000000 Z
+date: 2024-05-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -242,7 +242,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.3.26
 signing_key:
 specification_version: 4
 summary: Ruby gem to make ThreadLocalVars easy to use