aks · aks · May 26, 2023 · May 26, 2023
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -120,7 +120,7 @@ jobs:
 
       - deploy:
           name: Release and push
-          command: bundle exec rake install
+          command: bundle exec rake release
 
 workflows:
   version: 2

diff --git a/CHANGELOG.md b/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
diff --git a/Gemfile.lock b/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
diff --git a/README.md b/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

diff --git a/lib/thread_local_var_accessors.rb b/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 @@ def tlv_set_once(name, value = nil, &block)
   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

diff --git a/lib/thread_local_var_accessors/version.rb b/lib/thread_local_var_accessors/version.rb
@@ -1,3 +1,3 @@
 module ThreadLocalVarAccessors
-  VERSION = '0.1.2'
+  VERSION = '1.0.0'
 end
diff --git a/spec/lib/thread_local_var_accessors_spec.rb b/spec/lib/thread_local_var_accessors_spec.rb
@@ -199,14 +199,166 @@ def set_var(var_name, value)
     end
 
     describe 'tlv_new' do
-      subject { tlv.tlv_new(ivar_name) }
+      context 'without a default value' do
+        subject { tlv.tlv_new(ivar_name) }
 
-      it 'creates a new Conncurrent::ThreadLocalVar object' do
-        expect(subject).to be_a(Concurrent::ThreadLocalVar)
+        it 'creates a new Conncurrent::ThreadLocalVar object' do
+          expect(subject).to be_a(Concurrent::ThreadLocalVar)
+        end
+
+        it 'creates a TLV with no value' do
+          expect(subject.value).to be_nil
+        end
+
+        it 'has a default that is nil' do
+          expect(tlv.tlv_default(ivar_name)).to be_nil
+        end
+      end
+
+      context 'with a default value' do
+        subject { tlv.tlv_new(ivar_name, default_value) }
+        let(:default_value) { 42 }
+
+        it 'creates a new Conncurrent::ThreadLocalVar object' do
+          expect(subject).to be_a(Concurrent::ThreadLocalVar)
+        end
+
+        it 'creates a TLV with the default value' do
+          expect(subject.value).to eq default_value
+        end
+
+        it 'has a local value separate from the default' do
+          subject
+          tlv.tlv_set(ivar_name, 56)
+          expect(tlv.tlv_get(ivar_name)).to eq 56
+          expect(tlv.tlv_default(ivar_name)).to eq default_value
+        end
+
+        it 'has a default matching the original default value' do
+          subject
+          expect(tlv.tlv_default(ivar_name)).to eq default_value
+        end
+      end
+
+      context 'with a default block' do
+        subject { tlv.tlv_new(ivar_name, &default_block) }
+        let(:default_value) { 99 }
+        let(:default_block) { -> { default_value } }
+
+        it 'creates a new Conncurrent::ThreadLocalVar object' do
+          expect(subject).to be_a(Concurrent::ThreadLocalVar)
+        end
+
+        it 'creates a TLV with the default value' do
+          expect(subject.value).to eq default_value
+        end
+
+        it 'has a local value separate from the default' do
+          subject
+          tlv.tlv_set(ivar_name, 56)
+          expect(tlv.tlv_get(ivar_name)).to eq 56
+        end
+
+        it 'has a default matching the original default value' do
+          subject
+          expect(tlv.tlv_default(ivar_name)).to eq default_value
+        end
+      end
+    end
+
+    describe "#tlv_default" do
+      subject { tlv.tlv_default(ivar_name) }
+
+      context 'with no defined default' do
+        it { is_expected.to be_nil}
+      end
+
+      context 'with a defined default' do
+        before { tlv.tlv_init(ivar_name, 42) }
+
+        it { is_expected.to eq 42 }
+
+        context 'with a distinct value' do
+          before { tlv.tlv_set(ivar_name, 99) }
+          it { is_expected.to eq 42 }
+
+          it 'keeps the current thread value separate from the default' do
+            expect(tlv.tlv_get(ivar_name)).to eq 99
+          end
+        end
+      end
+    end
+
+    describe '#tlv_set_default' do
+      context 'with default value' do
+        subject { tlv.tlv_set_default(ivar_name, default) }
+        let(:default) { 44 }
+
+        it 'assigns the default on the existing TLVar' do
+          subject
+          expect(tlv.tlv_default(ivar_name)).to eq default
+        end
+
+        context 'with existing TLVars' do
+          before { subject }
+          it 'does not create new TLVar instance' do
+            expect(tlv).to_not receive(:tlv_init)
+            subject
+          end
+        end
+
+        context 'with new TLVar' do
+          before { tlv.instance_variable_set("@#{ivar_name}".to_sym, nil) }
+
+          it 'creates a new TLV' do
+            expect(tlv).to receive(:tlv_init)
+            subject
+          end
+
+          it 'installs the default' do
+            subject
+            expect(tlv.tlv_default(ivar_name)).to eq 44
+          end
+        end
       end
 
-      it 'creates a TLV with no value' do
-        expect(subject.value).to be_nil
+      context 'with default block' do
+        subject { tlv.tlv_set_default(ivar_name) { default } }
+        let(:default) { 44 }
+
+        it 'assigns the default on the existing TLVar' do
+          subject
+          expect(tlv.tlv_default(ivar_name)).to eq default
+        end
+
+        context 'with existing TLVars' do
+          before { subject }
+          it 'does not create new TLVar instance' do
+            expect(tlv).to_not receive(:tlv_init)
+            subject
+          end
+        end
+
+        context 'with new TLVar' do
+          before { tlv.instance_variable_set("@#{ivar_name}".to_sym, nil) }
+
+          it 'creates a new TLV' do
+            expect(tlv).to receive(:tlv_init)
+            subject
+          end
+
+          it 'installs the default' do
+            subject
+            expect(tlv.tlv_default(ivar_name)).to eq 44
+          end
+        end
+
+        context 'with both a default and a default block' do
+          subject { tlv.tlv_set_default(ivar_name, default) { default } }
+          it 'raises an error' do
+            expect { subject }.to raise_error(ArgumentError)
+          end
+        end
       end
     end
   end