thread_local_var_accessors 0.1.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b6e9d88de11a15e80e03d531bbb506da4b962e057ee1e88f0eb56f79c0eca74
-  data.tar.gz: 919b3b1100b7d8683317869cda3dbd87672ba6e30a0a86c565fffd0cefadcc99
+  metadata.gz: 44a2d47618384051b762c595994639af0699cde590462760853d3be02a611ffa
+  data.tar.gz: 4d4e3629f6bdfa482e5f080c6576d4a74d465a6b67c567b3c169db87e3b782fa
 SHA512:
-  metadata.gz: 2c1c294e53542491de381e69ff49b9b68942f6d5dc06ef8256f954dbec8af9c23396a4fd995d10701017b790c51880c6928c451c4e521c0b7cef80233af50aba
-  data.tar.gz: 740127f6247210b11f2ad478005eb459780afa6f50e451416b74a6ac35081d1ab818151b85bab786dd60031f71ee67cc01fc7b45423c454976f66834e000d0e0
+  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.1)
+    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
@@ -105,17 +115,30 @@ Then:
 
 ## Usage
 
-Use the class methods to declare instance getter and setter methods:
+To use the class methods, they must be included into the current module or class, with:
 
-    tlv_reader   :name1
-    tlv_writer   :name2
-    tlv_accessor :name3, :name4
+    class MyNewClass
+      include ThreadLocalVarAccessors
+        ...
+    end
+    
+With the include above, you can use the class methods to declare instance getter and setter methods:
+
+    class MyNewClass
+      include ThreadLocalVarAccessors
+
+      tlv_reader   :name1
+      tlv_writer   :name2
+      tlv_accessor :name3, :name4
+      
+    end
     
 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 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`.
 
@@ -130,9 +153,17 @@ Alternative block forms:
     tlv_set(name)      { |oldval| newval }
     tlv_set_once(name) { |oldval| newval }
 
-
 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:
+
+    @name1 ||= ThreadLocalVar.new
+    @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. 
+
 ### Example Usage
 
 ```ruby

data/lib/thread_local_var_accessors/version.rb

@@ -1,3 +1,3 @@
 module ThreadLocalVarAccessors
-  VERSION = '0.1.1'
+  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.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Alan Stebbens
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-28 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