win32-semaphore 0.3.2 → 0.4.0

data/CHANGES

@@ -1,3 +1,10 @@
+== 0.4.0 - 10-Jul-2012
+* Converted source to use FFI.
+* Refactored tests.
+* Now requires Ruby 1.9 or later.
+* Removed the Error class. Now uses SystemCallError (Errno::) internally if
+  a Windows function fails.
+
 == 0.3.2 - 23-Mar-2012
 * Refactored the Rakefile and cleaned up the gemspec.
 * Removed one test that was originally designed for the C version.

data/README

@@ -2,19 +2,18 @@
    An interface for MS Windows Semaphores.
 
 == Prerequisites
-   win32-ipc 0.5.0 or later.
+   win32-ipc 0.6.0 or later.
 
 == Installation
-   rake test (optional)
-   rake install
+   gem install win32-semaphore
 
 == Synopsis
    require 'win32/semaphore'
    include Win32
 
    Semaphore.new(1, 5, 'test') do |sem|
-      puts 'uh, oh' unless sem.wait(10) > 0
-      sem.release(2) # 2
+     puts 'uh, oh' unless sem.wait(10) > 0
+     sem.release(2) # 2
    end
 
 == Documentation
@@ -36,7 +35,7 @@
 
 == Known Bugs
    None known.  Any bugs should be reported on the project page at
-   http://www.github.com/djberg96/win32-semaphore
+   https://github.com/djberg96/win32-semaphore.
 
 == Future Plans
    Suggestions welcome.

data/lib/win32/semaphore.rb

@@ -3,143 +3,160 @@ require 'win32/ipc'
 # The Win32 module serves as a namespace only.
 module Win32
 
-   # The Semaphore class encapsulates semaphore objects on Windows.
-   class Semaphore < Ipc
-
-      # This is the error raised if any of the Semaphore methods fail.
-      class Error < StandardError; end
-
-      extend Windows::Synchronize
-      extend Windows::Error
-      extend Windows::Handle
-
-      # The version of the win32-semaphore library
-      VERSION = '0.3.2'
-
-      # The initial count for the semaphore object. This value must be greater
-      # than or equal to zero and less than or equal to +max_count+. The state
-      # of a semaphore is signaled when its count is greater than zero and
-      # nonsignaled when it is zero. The count is decreased by one whenever
-      # a wait function releases a thread that was waiting for the semaphore.
-      # The count is increased by a specified amount by calling
-      # Semaphore#release method.
-      #
-      attr_reader :initial_count
-
-      # The maximum count for the semaphore object. This value must be
-      # greater than zero.
-      #
-      attr_reader :max_count
-
-      # The name of the Semaphore object.
-      #
-      attr_reader :name
-
-      # Creates and returns new Semaphore object. If +name+ is omitted, the
-      # Semaphore object is created without a name, i.e. it's anonymous.
-      #
-      # If +name+ is provided and it already exists, then it is opened
-      # instead, and the +initial_count+ and +max_count+ parameters are
-      # ignored.
-      #
-      # The +initial_count+ and +max_count+ parameters set the initial count
-      # and maximum count for the Semaphore object, respectively. See the
-      # documentation for the corresponding accessor for more information.
-      #
-      # The +inherit+ attribute determines whether or not the semaphore can
-      # be inherited by child processes.
-      #
-      def initialize(initial_count, max_count, name=nil, inherit=true)
-         @initial_count = initial_count
-         @max_count = max_count
-         @name      = name
-         @inherit   = inherit
-
-         # Used to prevent potential segfaults.
-         if name && !name.is_a?(String)
-            raise TypeError, 'name must be a string'
-         end
-
-         if inherit
-            sec = 0.chr * 12 # sizeof(SECURITY_ATTRIBUTES)
-            sec[0,4] = [12].pack('L')
-            sec[8,4] = [1].pack('L') # 1 == TRUE
-         else
-            sec = 0
-         end
-
-         handle = CreateSemaphore(sec, initial_count, max_count, name)
-
-         if handle == 0 || handle == INVALID_HANDLE_VALUE
-            raise Error, get_last_error
-         end
-
-         super(handle)
-
-         if block_given?
-            begin
-               yield self
-            ensure
-               close
-            end
-         end
+  # The Semaphore class encapsulates semaphore objects on Windows.
+  class Semaphore < Ipc
+    ffi_lib :kernel32
+
+    private
+
+    class SecurityAttributes < FFI::Struct
+      layout(
+        :nLength, :ulong,
+        :lpSecurityDescriptor, :pointer,
+        :bInheritHandle, :bool
+      )
+    end
+
+    attach_function :CreateSemaphoreW, [:pointer, :long, :long, :buffer_in], :ulong
+    attach_function :OpenSemaphoreW, [:ulong, :bool, :buffer_in], :ulong
+    attach_function :ReleaseSemaphore, [:ulong, :long, :pointer], :bool
+
+    private_class_method :CreateSemaphoreW, :OpenSemaphoreW, :ReleaseSemaphore
+
+    SEMAPHORE_ALL_ACCESS = 0x1F0003
+    INVALID_HANDLE_VALUE = 0xFFFFFFFF
+
+    public
+
+    # The version of the win32-semaphore library
+    VERSION = '0.4.0'
+
+    # The initial count for the semaphore object. This value must be greater
+    # than or equal to zero and less than or equal to +max_count+. The state
+    # of a semaphore is signaled when its count is greater than zero and
+    # nonsignaled when it is zero. The count is decreased by one whenever
+    # a wait function releases a thread that was waiting for the semaphore.
+    # The count is increased by a specified amount by calling
+    # Semaphore#release method.
+    #
+    attr_reader :initial_count
+
+    # The maximum count for the semaphore object. This value must be
+    # greater than zero.
+    #
+    attr_reader :max_count
+
+    # The name of the Semaphore object.
+    #
+    attr_reader :name
+
+    # Creates and returns new Semaphore object. If +name+ is omitted, the
+    # Semaphore object is created without a name, i.e. it's anonymous.
+    #
+    # If +name+ is provided and it already exists, then it is opened
+    # instead, and the +initial_count+ and +max_count+ parameters are
+    # ignored.
+    #
+    # The +initial_count+ and +max_count+ parameters set the initial count
+    # and maximum count for the Semaphore object, respectively. See the
+    # documentation for the corresponding accessor for more information.
+    #
+    # The +inherit+ attribute determines whether or not the semaphore can
+    # be inherited by child processes.
+    #
+    def initialize(initial_count, max_count, name=nil, inherit=true)
+      @initial_count = initial_count
+      @max_count = max_count
+      @name      = name
+      @inherit   = inherit
+
+      if name && name.encoding.to_s != 'UTF-16LE'
+        name = name + 0.chr
+        name.encode!('UTF-16LE')
       end
 
-      # Open an existing Semaphore by +name+. The +inherit+ argument sets
-      # whether or not the object was opened such that a process created by the
-      # CreateProcess() function (a Windows API function) can inherit the
-      # handle. The default is true.
-      #
-      # This method is essentially identical to Semaphore.new, except that the
-      # options for +initial_count+ and +max_count+ cannot be set (since they
-      # are already set). Also, this method will raise a Semaphore::Error if
-      # the semaphore doesn't already exist.
-      #
-      # If you want "open or create" semantics, then use Semaphore.new.
-      #
-      def self.open(name, inherit=true, &block)
-         if name && !name.is_a?(String)
-            raise TypeError, 'name must be a string'
-         end
-
-         bool = inherit ? 1 : 0
-
-         # The OpenSemaphore() call here is strictly to force an error if the
-         # user tries to open a semaphore that doesn't already exist.
-         begin
-            handle = OpenSemaphore(SEMAPHORE_ALL_ACCESS, bool, name)
-
-            if handle == 0 || handle == INVALID_HANDLE_VALUE
-               raise Error, get_last_error
-            end
-         ensure
-            CloseHandle(handle)
-         end
-
-         self.new(0, 1, name, inherit, &block)
+      if inherit
+        sec = SecurityAttributes.new
+        sec[:nLength] = SecurityAttributes.size
+        sec[:bInheritHandle] = true
+      else
+        sec = nil
       end
 
-      # Increases the count of the specified semaphore object by +amount+.
-      # The default is 1. Returns the previous count of the semaphore if
-      # successful. If the +amount+ exceeds the +max_count+ specified when
-      # the semaphore was created then a Semaphore::Error is raised.
-      #
-      def release(amount = 1)
-         pcount = [0].pack('L')
+      handle = CreateSemaphoreW(sec, initial_count, max_count, name)
 
-         unless ReleaseSemaphore(@handle, amount, pcount)
-            raise Error, get_last_error
-         end
+      if handle == 0 || handle == INVALID_HANDLE_VALUE
+        raise SystemCallError.new("CreateSemaphore", FFI.errno)
+      end
+
+      super(handle)
 
-         pcount.unpack('L').first
+      if block_given?
+        begin
+          yield self
+        ensure
+          close
+        end
       end
+    end
+
+    # Open an existing Semaphore by +name+. The +inherit+ argument sets
+    # whether or not the object was opened such that a process created by the
+    # CreateProcess() function (a Windows API function) can inherit the
+    # handle. The default is true.
+    #
+    # This method is essentially identical to Semaphore.new, except that the
+    # options for +initial_count+ and +max_count+ cannot be set (since they
+    # are already set). Also, this method will raise a Semaphore::Error if
+    # the semaphore doesn't already exist.
+    #
+    # If you want "open or create" semantics, then use Semaphore.new.
+    #
+    def self.open(name, inherit=true, &block)
+      if name && name.encoding.to_s != 'UTF-16LE'
+        name = name + 0.chr
+        name.encode!('UTF-16LE')
+      end
+
+      begin
+        # The OpenSemaphore() call here is strictly to force an error if the
+        # user tries to open a semaphore that doesn't already exist.
+        handle = OpenSemaphoreW(SEMAPHORE_ALL_ACCESS, inherit, name)
 
-      # Returns whether or not the object was opened such that a process
-      # created by the CreateProcess() function (a Windows API function) can
-      # inherit the handle. The default is true.
-      #
-      def inheritable?
-         @inherit
+        if handle == 0 || handle == INVALID_HANDLE_VALUE
+          raise SystemCallError.new("OpenSemaphore", FFI.errno)
+        end
+      ensure
+        CloseHandle(handle)
       end
-   end
+
+      self.new(0, 1, name, inherit, &block)
+    end
+
+    # Increases the count of the specified semaphore object by +amount+.
+    # The default is 1. Returns the previous count of the semaphore if
+    # successful. If the +amount+ exceeds the +max_count+ specified when
+    # the semaphore was created then an error is raised.
+    #
+    def release(amount = 1)
+      pcount = FFI::MemoryPointer.new(:long)
+
+      # Ruby doesn't translate error 298, so we treat it as an EINVAL
+      unless ReleaseSemaphore(@handle, amount, pcount)
+        errno = FFI.errno
+        errno = 22 if errno == 298 # 22 is EINVAL
+        raise SystemCallError.new("ReleaseSemaphore", errno)
+      end
+
+      pcount.read_long
+    end
+
+    # Returns whether or not the object was opened such that a process
+    # created by the CreateProcess() function (a Windows API function) can
+    # inherit the handle. The default is true.
+    #
+    def inheritable?
+      @inherit
+    end
+  end
 end

data/test/test_win32_semaphore.rb

@@ -1,5 +1,5 @@
 ################################################################
-# test_semaphore.rb
+# test_win32_semaphore.rb
 #
 # Test suite for the win32-semaphore package. This test should
 # be run via the 'rake test' task.
@@ -13,53 +13,114 @@ class TC_Semaphore < Test::Unit::TestCase
     @sem = Semaphore.new(1, 3, 'test')
   end
 
-  def test_version
-    assert_equal('0.3.2', Semaphore::VERSION)
+  test "version is set to expected value" do
+    assert_equal('0.4.0', Semaphore::VERSION)
   end
 
-  def test_open
-    assert_respond_to(Semaphore, :open)
-    assert_nothing_raised{ Semaphore.open('test'){} }
-    assert_raises(Semaphore::Error){ Semaphore.open('bogus'){} }
+  test "initial_count basic functionality" do
+    assert_respond_to(@sem, :initial_count)
+  end
+
+  test "initial count is set to value passed to constructor" do
+    assert_equal(1, @sem.initial_count)
+  end
+
+  test "max_count basic functionality" do
+    assert_respond_to(@sem, :max_count)
+  end
+
+  test "max_count is set to value passed to constructor" do
+    assert_equal(3, @sem.max_count)
+  end
+
+  test "name method basic functionality" do
+    assert_respond_to(@sem, :name)
+  end
+
+  test "name returns value passed in constructor" do
+    assert_equal('test', @sem.name)
+  end
+
+  test "default name is nil" do
+    sem = Semaphore.new(0,1)
+    assert_nil(sem.name)
+    sem.close
   end
 
-  def test_inheritable
+  test "inheritable? method is defined and true by default" do
     assert_respond_to(@sem, :inheritable?)
-    assert_equal(true, @sem.inheritable?)
+    assert_true(@sem.inheritable?)
   end
 
-  def test_release
+  test "inheritable? method returns value passed to constructor" do
+    sem = Semaphore.new(0,1,nil,false)
+    assert_false(sem.inheritable?)
+    sem.close
+  end
+
+  test "release method basic functionality" do
     assert_respond_to(@sem, :release)
+    assert_kind_of(Fixnum, @sem.release)
+  end
+
+  test "release accepts an optional amount" do
+    assert_equal(1, @sem.release(1))
+  end
+
+  test "release returns the total number of releases" do
     assert_equal(1, @sem.release(1))
     assert_equal(2, @sem.release(1))
-    assert_raises(Semaphore::Error){ @sem.release(99) }
   end
 
-  def test_wait
+  test "attempting to release more than the total count raises an error" do
+    assert_raise(Errno::EINVAL){ @sem.release(99) }
+  end
+
+  test "release only accepts one argument" do
+    assert_raise(ArgumentError){ @sem.release(1,2) }
+  end
+
+  test "open method basic functionality" do
+    assert_respond_to(Semaphore, :open)
+    assert_nothing_raised{ Semaphore.open('test'){} }
+  end
+
+  test "open method fails is semaphore name is invalid" do
+    assert_raise(Errno::ENOENT){ Semaphore.open('bogus'){} }
+  end
+
+  test "wait method was inherited" do
     assert_respond_to(@sem, :wait)
   end
 
-  def test_wait_any
+  test "wait_any method was inherited" do
     assert_respond_to(@sem, :wait_any)
   end
 
-  def test_wait_all
+  test "wait_all method was inherited" do
     assert_respond_to(@sem, :wait_all)
   end
 
-  def test_valid_constructor
-    assert_nothing_raised{ Semaphore.new(0, 1){} }
-    assert_nothing_raised{ Semaphore.new(0, 1, "foo"){} }
-    assert_nothing_raised{ Semaphore.new(0, 1, "foo", false){} }
+  test "first argument to constructor must be a number" do
+    assert_raise(TypeError){ Semaphore.new('foo', 1){} }
+  end
+
+  test "second argument to constructor must be a number" do
+    assert_raise(TypeError){ Semaphore.new(1, 'bar'){} }
+  end
+
+  test "constructor accepts a maximum of four arguments" do
+    assert_raise(ArgumentError){ Semaphore.new(1, 2, 'test', true, 1){} }
   end
 
-  def test_invalid_constructor
-    assert_raises(TypeError){ Semaphore.new("foo", "bar"){} }
-    assert_raises(ArgumentError){ Semaphore.new(1, 1, "test", 1, 1){} }
+  test "ffi functions are private" do
+    assert_not_respond_to(Semaphore, :CreateSemaphoreW)
+    assert_not_respond_to(Semaphore, :OpenSemaphoreW)
+    assert_not_respond_to(Semaphore, :ReleaseSemaphore)
   end
 
   def teardown
-    @sem.close
+    @sem.close if @sem
     @sem = nil
   end
 end

data/win32-semaphore.gemspec

@@ -2,7 +2,7 @@ require 'rubygems'
 
 Gem::Specification.new do |spec|
   spec.name        = 'win32-semaphore'
-  spec.version     = '0.3.2'
+  spec.version     = '0.4.0'
   spec.author      = 'Daniel J. Berger'
   spec.license     = 'Artistic 2.0'
   spec.email       = 'djberg96@gmail.com'
@@ -13,6 +13,7 @@ Gem::Specification.new do |spec|
 
   spec.rubyforge_project = 'win32utils'
   spec.extra_rdoc_files  = ['README', 'CHANGES', 'MANIFEST']
+  spec.required_ruby_version = '> 1.9.0'
 
   spec.add_dependency('win32-ipc')
   spec.add_development_dependency('test-unit')

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: win32-semaphore
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-03-23 00:00:00.000000000 Z
+date: 2012-07-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: win32-ipc
-  requirement: &24606430 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,15 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *24606430
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: test-unit
-  requirement: &24606160 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,7 +37,12 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *24606160
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: ! "    The win32-semaphore library provides an interface to semaphore
   objects\n    on MS Windows. A semaphore is a kernel object used for resource counting.\n
   \   This allows threads to query the number of resources available, and wait\n    if
@@ -63,9 +73,9 @@ require_paths:
 required_ruby_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ! '>='
+  - - ! '>'
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.9.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -74,7 +84,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: win32utils
-rubygems_version: 1.8.11
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: Interface to MS Windows Semaphore objects.