thread_local_var_accessors 0.1.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f567c363dc63194dc30aeae5d661ea14c871f9f64cc65ed3d2c2947447d1fc91
-  data.tar.gz: 30c3bc0763221a483de2370af6843c83b39ff6429f27f1b6ad796931fa9dae51
+  metadata.gz: 44a2d47618384051b762c595994639af0699cde590462760853d3be02a611ffa
+  data.tar.gz: 4d4e3629f6bdfa482e5f080c6576d4a74d465a6b67c567b3c169db87e3b782fa
 SHA512:
-  metadata.gz: 59329574532e6730a71d3f44d011bedae930ee29a0b592f9ff8fbf7ed6d824a13cb65ab9f51edb40df372615c5975f459bd483fc467f5914af48f992a21f7cfc
-  data.tar.gz: 822c3f467f172562efdab7a38cc73063b42b8937f09d71ad01345c52d80fa69bc438a60067756386aa8d4d8ba74055513cd4303875a3784b13a5d07e3120adcc
+  metadata.gz: e840c90fd9f096762ee4fd12ba5c4cffc9fb6952af177375327e04395cd9734a572542f1301ada916704daa507c21aaf42d4543d4dd01538e85bdf652a631c34
+  data.tar.gz: 826a2db9381d3f7ab70482b0c866427554e58e4c7d70e238964e34593437add0d276067a21aa2e2775f8b9dc050cf05e99776f56374f330dd2a9e952738ecda7

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.0.0)
       concurrent-ruby
 
 GEM
@@ -87,4 +87,4 @@ DEPENDENCIES
   yard
 
 BUNDLED WITH
-   2.4.6
+   2.4.12

data/README.md

@@ -49,12 +49,22 @@ 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 
+variable and there has been no thread-specific value assignment.
+
+The TLV default value is used across *all* threads.
+
+    tlv_init(:timeout, _default_)
+    tlv_init(:timeout) { _default_ }
 
 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

data/lib/thread_local_var_accessors/version.rb

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

data/lib/thread_local_var_accessors.rb

@@ -31,18 +31,67 @@
 # becomes very simple:
 #
 #     tlv_accessor :timeout
-#     ...
+#
+# Create a new TLV instance with an associated default, applied across all threads.
+#
+#     tlv_init :timeout, default_timeout
+#
+#     tlv_init :timeout { default_timeout }
+#
+#
+# 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:
+#
 #     self.timeout = 0.5  # stores the TLV value just for this thread
 #
-# Alternative ways to initialize:
+# 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
 #
+# 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_init(: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 }
+#
+# 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.
+#
+# 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.
+#
+# 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 +135,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:
 #
@@ -170,9 +220,39 @@ module ThreadLocalVarAccessors
   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
-  def tlv_new(name)
-    instance_variable_set(name.to_ivar, Concurrent::ThreadLocalVar.new)
+  # @example Default argument
+  #   tlv_init(:ivar, default_value)
+  # @example Default block
+  #   tlv_init(:ivar) { default_value }
+  def tlv_init(name, default=nil, &block)
+    instance_variable_set(name.to_ivar, Concurrent::ThreadLocalVar.new(default, &block))
+  end
+  alias tlv_new tlv_init
+
+  # Fetches the default value for the TLVar
+  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)
+    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
+    else
+      tlv_init(name, default, &block)
+    end
   end
 
   # @!visibility private

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.0.0
 platform: ruby
 authors:
 - Alan Stebbens
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-04-05 00:00:00.000000000 Z
+date: 2023-05-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -199,6 +199,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - Gemfile
 - Gemfile.lock
 - LICENSE