resource_warden 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6156e0930be5bea9d2114a52a5d23fe29cb466b36b2733f58861af2968a80ef5
-  data.tar.gz: 3124064d103b827665d952445cdbdf53898d02a7a4a6c36fda1c8831a81e3ef8
+  metadata.gz: a0524384f21128a12d22d6ef50d0a433c2bb5640e95057b909d0cddddd3e509e
+  data.tar.gz: 59e2f42a77d5f21f165623c5a4c31a2a99c373d8b8dd209f46eae8ca3945046c
 SHA512:
-  metadata.gz: 794209e8d0d9740b9f4dbdabef32176779fcfc0ca43ed62a6225eacbd4e2a7c19af919089338536d16e59e494768415a1d16907688a16e767c5133cf8569c135
-  data.tar.gz: 7ade6cfad2a4eeb07eca26f5239577d3e3cc9204ed7f4c60f4505d5359ae5a7bc32079a7f328239abef28f2c35de6d8067e6248f166ad9eb2466d13971d33dbe
+  metadata.gz: 0ec2387e3c5d99d2508d1e10941d0caa398f2665236ef59896a01ab9de61d75ae2505d1ed66c87ba41913a0ac72045020d29d66d5add93fa5ce6958c82450845
+  data.tar.gz: 92292cd7e7c31112d81d71f4acdc78cded5d0d86759c7ede33d85e263168ef2bb5f57f13ee792dbdba1959e7beb8546ad8d8898760425988bb3113509441ea09

data/lib/ResourceWarden/Key.rb

@@ -1,9 +1,14 @@
+##
+# A class encapsulating a single use Proc to change the owner of a resource to the thread that request a resource key
 class Key
   class ReuseException < Exception; end
   def initialize(&block)
     @proc = Proc.new(&block)
   end
 
+  ##
+  # Calls the Proc created by the resource cell which switches the owner of the resource to the thread that requested the key
+  # This is the only intended way to obtain ownership of a resource
   def use
     throw ReuseException.new("A key can only be used once") unless @proc.is_a?(Proc)
 

data/lib/ResourceWarden/ResourceCell.rb

@@ -1,4 +1,5 @@
 require_relative './Key'
+##
 # wraps a resource to ensure only a keyholder can execute code
 module ResourceWarden
   class ResourceCell
@@ -14,16 +15,18 @@ module ResourceWarden
       @registry = []
     end
 
+    ##
     # changes the heir to the caller and builds a connector proc to wait on the current thread
     def get_key
       heir = nil
+      thread = Thread.current
       @registration.synchronize do
         heir = @heir
         @heir = Thread.current
       end
       Key.new do
         heir&.join
-        chown(Thread.current)
+        chown(thread)
         Unlock.new
       end
     end
@@ -43,6 +46,9 @@ module ResourceWarden
       throw JailbreakException.new("A thread must first use a resource key before accessing a resource")
     end
 
+    ##
+    # Responds only to public methods of the resource cell until the calling thread owns the resource then responds
+    # resource methods as well
     def respond_to_missing?(method_name, include_private = false)
       super || Thread.current == @owner && @resource.respond_to?(method_name, include_private)
     end

data/lib/ResourceWarden/Warden.rb

@@ -1,4 +1,5 @@
-# Resource Exclusion class
+##
+# Resource Exclusion module
 # A block is passed which will then be encapsulated in a thread immediately joined by the current thread.
 # This allows requests for multiple resources and guarantees a lock on all resources will be granted
 # as soon as all prior virtual threads with a claim on a resource terminate.
@@ -13,24 +14,35 @@ module ResourceWarden
     @mutex = Mutex.new
     @registration = Mutex.new
 
+    ##
+    # takes a list of resources which constitute a block of resources that must be obtained as a group
     def initialize(*resources)
       @cell_block = resources || []
       @block_mutex = Mutex.new
     end
 
+    ##
+    # adds a resource to the exclusive resource block
+    # @param resource [ResourceWarden::ResourceCell]
     def add(resource)
       @block_mutex.synchronize { @cell_block << resource }
     end
 
+    ##
+    # @return [Array<ResourceWarden::ResourceCell>]
     def resources
       @cell_block
     end
 
+    ##
+    # Runs a block of code with exclusive access to all resources in the block
     def synchronize(&block)
       @block_mutex.synchronize { Warden.synchronize(*@cell_block, &block) }
     end
 
-    # global synchronization
+    ##
+    # Runs a block of code with exclusive access to a list of resources
+    # @param resources [ResourceWarden::ResourceCell]
     def self.synchronize(*resources, &block)
       keys = []
       # creating a virtual thread to guarantee the owning thread is joinable
@@ -42,7 +54,8 @@ module ResourceWarden
     end
 
 
-    # creates a resource
+    ##
+    # Takes a object or block and creates a resource from the object or output of the block respectively
     def self.create(object = nil)
       @registration.synchronize do
         item = block_given? ? yield : object

data/lib/ResourceWarden/types.rbs

@@ -1,16 +1,10 @@
 # Transparent wrapper class ignores requests from any caller other than the current owner
 module ResourceWarden
   class ResourceCell
-    # Creates the cell that will only allow a owning thread to call any method of the resource
     def initialize: (untyped) -> void
-    # creates a blocking resource key that can only be used once to change the owner of the resource to the calling thread
     def get_key: -> void
-
-    # returns the current resource owner
     private def owner: -> Thread
     private def chown: (Thread) -> void
-
-    # resource guard method
     private def method_missing: (Symbol | String, *untyped) -> untyped
     private def respond_to_missing?: (Symbol | String, *untyped) -> bool
 
@@ -20,24 +14,16 @@ module ResourceWarden
   end
 
   class Warden
-    # warden instance handles a specific resource group
     def intialize: (*ResourceCell) -> void
-    # synchronize a block with all resource under the wardens management
     def synchronize: () { () -> BasicObject } -> void
-    # puts a resource under this wardens management
     def add: (ResourceCell) -> void
-    # returns the resources managed by this warden
     def resources: () -> Array[ResourceCell]
-    # synchronizes a block with a resource list
-    def self.synchronize:(*Symbol) { () -> BasicObject } -> void
-    # creates a resourceCell either from an object or a cell
+    def self.synchronize:(*ResourceCell) { () -> BasicObject } -> void
     def self.create:(untyped) -> ResourceCell | () { () -> Object } -> ResourceCell
   end
 
   class Key
-    # creates a key this should only be created by a resource cell
     def initialize: () {() -> ResourceCell::Unlock } -> void
-    # changes the owner of the creating cell to the current thread after waiting for prior threads to complete
     def use: () -> void
   end
 end

data/lib/ResourceWarden/version.rb

@@ -1,3 +1,3 @@
 module ResourceWarden
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: resource_warden
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Aaron Deibele
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-05-03 00:00:00.000000000 Z
+date: 2022-05-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler