thread-local 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96d9a2bba22cf0213da7a37e9834689cda7727e256bee89402006ddde7c34aa6
-  data.tar.gz: 64a871588d675a66599a36aa04a2353a844063bf88ad9af500064d42aad37a86
+  metadata.gz: 6f4032930cf7762d586307e1bb9ced4d69b2d3f72b5f1165c616df4df6a96d85
+  data.tar.gz: da327e71a8e4b8c7ad46aac6bbb3a8036142a6fee070db816dbec9dcf73861f7
 SHA512:
-  metadata.gz: ab2d8d85eaa85e6d30d30b1b28613393f447b1ecee6e278f50135641f1ab1d9507bb036d8c57d025f98605300cb69d20cc2af29edc2f2611f6153bf5a09625b9
-  data.tar.gz: b52551c7a93f1de9ccae111a2f8ad3acafcac461c88bb40e5de953fa3a27f199f68931ed545c23eefc8ed318478f76d592fe44808fdb9d1cc711454f9075bec8
+  metadata.gz: 56bca34b696ab47635edbd9bfd9dd4099f59a57cccdfd795aae7b5eec739f7fb166282e383b9f546964be0251b3a4cdf08320a399f9e260c85e35cb6e762487a
+  data.tar.gz: 101f513ddd1a8b5900dc7ae68e7398dacd5e80418b8d9e755a130fb719c2658eb1c84dd7c25b3f8d728061bece1fb57b3baee430b7d29100308e87de08099f6a

data/lib/thread/local.md

@@ -0,0 +1,81 @@
+# Thread::Local
+
+Implements a standard interface for per-class/module thread local instances.
+
+## Per-Class Instance
+
+By default, classes are instantiated using `self.new`:
+
+~~~ ruby
+require 'thread/local'
+
+class MyClass
+	extend Thread::Local
+end
+
+p MyClass.instance
+~~~
+
+### Extensions
+
+If you need to change the behaviour of an existing thread local, you can prepend a module to wrap the call to `self.new`:
+
+~~~ ruby
+require 'thread/local'
+
+class MyClass
+	extend Thread::Local
+	
+	attr_accessor :data
+end
+
+module MyExtension
+	def local
+		instance = super
+		
+		# Do something with the thread local instance, e.g.:
+		instance.data = [1, 2, 3]
+		
+		return instance
+	end
+end
+
+MyClass.extend(MyExtension)
+
+p MyClass.instance
+~~~
+
+### Assignment
+
+Generally, you should avoid assigning to the thread-local instance. You should prefer extensions as outlined above. However, in some situations (e.g. testing) you may prefer to directly assign to the thread local:
+
+~~~ruby
+require 'thread/local'
+
+class MyClass
+	extend Thread::Local
+end
+
+# Change the instance for the current thread:
+MyClass.instance = Object.new
+
+p MyClass.instance
+~~~
+
+## Per-Module Instance
+
+By default, you cannot instantiate a module. So, you must implement your own `self.new` method:
+
+~~~ ruby
+require 'thread/local'
+
+module MyModule
+	extend Thread::Local
+	
+	def self.new
+		Object.new
+	end
+end
+
+p MyModule.instance
+~~~

data/lib/thread/local.rb

@@ -20,25 +20,37 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
-require "thread/local/version"
+require_relative "local/version"
 
 class Thread
 	module Local
 		# Instantiate a new thread-local object.
+		# By default, invokes {new} to generate the instance.
+		# @returns [Object]
 		def local
 			self.new
 		end
 		
 		# Get the current thread-local instance. Create it if required.
-		def instance(thread = Thread.current)
+		# @returns [Object] The thread-local instance.
+		def instance
+			thread = Thread.current
 			name = self.name
 			
 			unless instance = thread.thread_variable_get(name)
-				instance = self.local
-				thread.thread_variable_set(name, instance)
+				if instance = self.local
+					thread.thread_variable_set(name, instance)
+				end
 			end
 			
 			return instance
 		end
+		
+		# Assigns the current thread-local instance.
+		# @parameter instance [Object] The object that will become the thread-local instance.
+		def instance= instance
+			thread = Thread.current
+			thread.thread_variable_set(self.name, instance)
+		end
 	end
 end

data/lib/thread/local/version.rb

@@ -20,10 +20,8 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
-require 'thread'
-
 class Thread
 	module Local
-		VERSION = "1.0.0"
+		VERSION = "1.1.0"
 	end
 end

metadata

@@ -1,29 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: thread-local
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Samuel Williams
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-02-22 00:00:00.000000000 Z
+date: 2020-08-10 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: covered
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -39,7 +25,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rspec
+  name: covered
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -53,7 +39,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -66,27 +52,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: 
+description:
 email:
-- samuel.williams@oriontransfer.co.nz
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".github/workflows/development.yml"
-- ".gitignore"
-- ".rspec"
-- Gemfile
-- README.md
-- Rakefile
+- lib/thread/local.md
 - lib/thread/local.rb
 - lib/thread/local/version.rb
-- thread-local.gemspec
-homepage: 
+homepage: https://github.com/socketry/thread-local
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -94,7 +73,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.3.0
+      version: 2.5.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -102,7 +81,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.1.2
-signing_key: 
+signing_key:
 specification_version: 4
 summary: Provides a class-level mixin to make thread local state easy.
 test_files: []

data/.github/workflows/development.yml

@@ -1,34 +0,0 @@
-name: Development
-
-on: [push, pull_request]
-
-jobs:
-  test:
-    strategy:
-      matrix:
-        os:
-          - ubuntu
-          - macos
-        
-        ruby:
-          - 2.4
-          - 2.5
-          - 2.6
-          - 2.7
-        
-        include:
-          - os: 'ubuntu'
-            ruby: '2.6'
-            env: COVERAGE=PartialSummary,Coveralls
-    
-    runs-on: ${{matrix.os}}-latest
-    
-    steps:
-    - uses: actions/checkout@v1
-    - uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: ${{matrix.ruby}}
-    - name: Install dependencies
-      run: bundle install
-    - name: Run tests
-      run: ${{matrix.env}} bundle exec rspec

data/.gitignore

@@ -1,12 +0,0 @@
-/.bundle/
-/.yardoc
-/_yardoc/
-/coverage/
-/doc/
-/pkg/
-/spec/reports/
-/tmp/
-
-# rspec failure tracking
-.rspec_status
-Gemfile.lock

data/.rspec

@@ -1,3 +0,0 @@
---format documentation
---color
---require spec_helper

data/Gemfile

@@ -1,4 +0,0 @@
-source "https://rubygems.org"
-
-# Specify your gem's dependencies in thread-local.gemspec
-gemspec

data/README.md

@@ -1,85 +0,0 @@
-# Thread::Local ![Development](https://github.com/socketry/thread-local/workflows/Development/badge.svg?branch=master)
-
-A module to simplify thread-local state.
-
-## Motivation
-
-In my own web framework, [utopia](https://github.com/socketry/utopia), I have been struggling with the best way to expose configuration details. I was setting both global variables and modifying `ENV` which made it impossible to have multiple isolated instances of the application in the same process. This in turn makes it hard to implement things like graceful restart in multi-threaded [falcon](https://github.com/socketry/falcon). Such issues also affect application code running in other multi-threaded contexts, which are becoming increasingly common (e.g. JRuby, TruffleRuby).
-
-Global variables are often not thread-safe and encourage poor programming style. In many cases it is desirable to have thread-local state, but implementing this directly in Ruby is unpleasant at best. This gem provides a best-practice wrapper which can extend existing classes to provide per-thread instances.
-
-Conceptually, a thread is a container for application state. This works well when servers consider applications to be isolated on a per-thread basis, but this isn't always the case:
-
-| Server               | Application      | Thread Safety            |
-|----------------------|------------------|--------------------------|
-| Falcon Multi-Process | One per process. | Isolated.                |
-| Falcon Multi-Thread  | One per thread.  | Isolated, Shared State.  |
-| Puma Multi-Thread    | One per process. | Reentrant, Shared State. |
-| Puma Cluster         | One per worker.  | Reentrant, Shared State. |
-| Unicorn              | One per process. | Isolated.                |
-
-Puma requires applications to be completely thread safe and reentrant, which isn't always easy. However, this gem attempts to provide a model which works in all the above servers, providing isolated, thread-safe, mutable per-thread state.
-
-## Installation
-
-```
-bundle add thread-local
-```
-
-## Usage
-
-In your own class:
-
-```ruby
-class MyThing
-	extend Thread::Local
-end
-```
-
-Now, instead of instantiating your class `MyThing.new`, use `MyThing.instance`. It will return a thread-local instance.
-
-```ruby
-Thread.new do
-	MyThing.instance
-	# => #<MyObject:0x000055a14ec6be80>
-end
-
-Thread.new do
-	MyThing.instance
-	# => #<MyObject:0x000055a14ec597d0>
-end
-```
-
-Use this as a thread-safe alternative to globals.
-
-## Contributing
-
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
-
-## License
-
-Released under the MIT license.
-
-Copyright, 2020, by [Samuel G. D. Williams](https://www.codeotaku.com).
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.

data/Rakefile

@@ -1,6 +0,0 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-
-RSpec::Core::RakeTask.new(:spec)
-
-task :default => :spec

data/thread-local.gemspec

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-# Copyright, 2020, by Samuel G. D. Williams. <http://www.codeotaku.com>
-# 
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-# 
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-# 
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-# THE SOFTWARE.
-
-require_relative 'lib/thread/local/version'
-
-Gem::Specification.new do |spec|
-	spec.name = "thread-local"
-	spec.version = Thread::Local::VERSION
-	spec.authors = ["Samuel Williams"]
-	spec.email = ["samuel.williams@oriontransfer.co.nz"]
-	
-	spec.summary = "Provides a class-level mixin to make thread local state easy."
-	spec.license = "MIT"
-	spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
-	
-	spec.files = Dir.chdir(File.expand_path('..', __FILE__)) do
-		`git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
-	end
-	
-	spec.require_paths = ["lib"]
-	
-	spec.add_development_dependency "covered"
-	spec.add_development_dependency "bundler"
-	spec.add_development_dependency "rspec"
-	spec.add_development_dependency "rake"
-end