process_shared 0.0.2 → 0.0.3

data/lib/process_shared.rb

@@ -1,6 +1,6 @@
 require 'ffi'
 
-if VERSION =~ /^1.8/
+if RUBY_VERSION =~ /^1.8/
   require 'process_shared/define_singleton_method'
   
   module ProcessShared

data/lib/process_shared/bounded_semaphore.rb

@@ -2,6 +2,9 @@ require 'process_shared/psem'
 require 'process_shared/semaphore'
 
 module ProcessShared
+  # BoundedSemaphore is identical to Semaphore except that its value
+  # is not permitted to rise above a maximum.  When the value is at
+  # the maximum, calls to #post will have no effect.
   class BoundedSemaphore < Semaphore
     # With no associated block, open is a synonym for
     # Semaphore.new. If the optional code block is given, it will be

data/lib/process_shared/mutex.rb

@@ -4,12 +4,27 @@ require 'process_shared/shared_memory'
 require 'process_shared/process_error'
 
 module ProcessShared
+  # This Mutex class is implemented as a BoundedSemaphore with a
+  # maximum value of 1.  Additionally, the locking process is tracked,
+  # and ProcessError is raised if either #unlock is called by a
+  # process different from the locking process, or if #lock is called
+  # while the process already holds the lock (i.e. the mutex is not
+  # re-entrant).  This tracking is not without performance cost, of
+  # course (current implementation uses an additional BoundedSemaphore
+  # and SharedMemory segment).
+  #
+  # The API is intended to be identical to the ::Mutex in the core
+  # Ruby library.
+  #
+  # TODO: the core Ruby api has no #close method, but this Mutex must
+  # release its BoundedSemaphore and SharedMemory resources.  For now,
+  # we rely on the object finalizers of those objects...
   class Mutex
-    include WithSelf
+    # include WithSelf
 
-    def self.open(&block)
-      new.with_self(&block)
-    end
+    # def self.open(&block)
+    #   new.with_self(&block)
+    # end
 
     def initialize
       @internal_sem = BoundedSemaphore.new(1)
@@ -73,6 +88,8 @@ module ProcessShared
 
     # Acquire the lock, yield the block, then ensure the lock is
     # unlocked.
+    #
+    # @return [Object] the result of the block
     def synchronize
       lock
       begin

data/lib/process_shared/semaphore.rb

@@ -44,7 +44,8 @@ module ProcessShared
       psem_post(sem, err)
     end
 
-    # Get the current value of the semaphore.
+    # Get the current value of the semaphore. Raises Errno::NOTSUP on
+    # platforms that don't support this (e.g. Mac OS X).
     #
     # @return [Integer] the current value of the semaphore.
     def value
@@ -53,6 +54,11 @@ module ProcessShared
       int.get_int(0)
     end
 
+    # Release the resources associated with this semaphore.  Calls to
+    # other methods are undefined after #close has been called.
+    #
+    # Close must be called when the semaphore is no longer needed.  An
+    # object finalizer will close the semaphore as a last resort.
     def close
       psem_close(sem, err)
     end

data/spec/spec_helper.rb

@@ -1,4 +1,4 @@
-require 'rubygems' if VERSION =~ /^1.8/
+require 'rubygems' if RUBY_VERSION =~ /^1.8/
 gem 'minitest'
 require 'minitest/spec'
 require 'minitest/autorun'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: process_shared
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 25
   prerelease: 
   segments: 
   - 0
   - 0
-  - 2
-  version: 0.0.2
+  - 3
+  version: 0.0.3
 platform: ruby
 authors: 
 - Patrick Mahoney