win32-semaphore 0.3.0

data/CHANGES

@@ -0,0 +1,33 @@
+== 0.3.0 - 3-May-2007
+* Now pure Ruby.
+* Added a Rakefile, with test, install and example tasks.
+* Both the Semaphore.new and Semaphore.open methods now accept a block, and
+  automatically close the associated handle at the end of the block.
+* The Semaphore.new method now accepts an optional fourth argument that
+  controls whether the Event object can be inherited by other processes.
+* Added a gemspec.
+* Removed the doc/semaphore.txt file. The documentation is now inlined via
+  RDoc. There is also some documentation in the README file.
+
+== 0.2.2 - 10-Jun-2005
+* Now Unicode friendly.
+* Inlined rdoc documentation into the C source code.
+* Made the semaphore.txt file rdoc friendly.
+* Removed the semaphore.rd file.
+
+== 0.2.1 - 1-Mar-2005
+* Added a VERSION constant (oops).
+* Moved the 'examples' directory to the toplevel directory.
+* Made the CHANGES and README files rdoc friendly.
+* Removed an unused (and unnecessary) helper function in semaphore.h.
+
+== 0.2.0 - 16-Jul-2004
+* Modified to use the newer allocation framework.  This means that as of this
+  release, this package requires Ruby 1.8.0 or later.
+* Fixed a bug in the constructor where it was possible for the constructor to
+  fail, but have no error raised.
+* Moved the test.rb file to the doc/examples directory.
+* Added more tests.
+
+== 0.1.0 - 14-May-2004
+* Initial release

data/MANIFEST

@@ -0,0 +1,8 @@
+* CHANGES
+* MANIFEST
+* README
+* Rakefile
+* win32-semaphore.gemspec
+* examples/semaphore_test.rb
+* lib/win32/semaphore.rb
+* test/tc_semaphore.rb

data/README

@@ -0,0 +1,58 @@
+== Brief Description
+   An interface for MS Windows Semaphores.
+
+== Prerequisites
+   win32-ipc 0.5.0 or later.
+
+== Installation
+   rake test (optional)
+   rake install
+
+== 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
+   end
+
+== Documentation
+   The event.rb file contains inline RDoc documentation. If you installed
+   this file as a gem, then you have the docs.
+
+   For more detailed documentation about Semaphores on MS Windows in general,
+   please visit http://www.msdn.com/library and lookup the CreateSemaphore(),
+   OpenSemaphore() and ReleaseSemaphore() functions.
+
+== Notes
+   The Semaphore class is a subclass of Win32::Ipc (win32-ipc). This package
+   require's the win32-ipc package internally (you don't need to explicitly
+   call it).
+
+== Acknowledgements
+   Adapted originally from the Win32::Semaphore Perl module by Christopher
+   J. Madsen.
+
+== Known Bugs
+   None known.  Any bugs should be reported on the project page at
+   http://rubyforge.org/projects/win32utils.
+
+== Future Plans
+   Suggestions welcome.
+
+== License
+   Ruby's
+
+== Copyright
+   (C) 2003-2007 Daniel J. Berger
+   All Rights Reserved	
+
+== Warranty
+   This package is provided "as is" and without any express or
+   implied warranties, including, without limitation, the implied
+   warranties of merchantability and fitness for a particular purpose.
+
+== Author(s)
+   Daniel J. Berger
+   Park Heesob

data/Rakefile

@@ -0,0 +1,26 @@
+require 'rake'
+require 'rake/testtask'
+require 'rbconfig'
+include Config
+
+desc 'Install the win32-semaphore package (non-gem)'
+task :install do
+   sitelibdir = CONFIG['sitelibdir']
+   installdir = File.join(sitelibdir, 'win32')
+   file = 'lib\win32\semaphore.rb'
+
+   Dir.mkdir(installdir) unless File.exists?(installdir)
+   FileUtils.cp(file, installdir, :verbose => true)
+end
+
+desc 'Run the example program'
+task :example do
+   ruby '-Ilib examples/semaphore_test.rb'
+end
+
+Rake::TestTask.new do |t|
+   t.libs << 'test'
+   t.verbose = true
+   t.warning = true
+   t.test_files = FileList['test/tc_semaphore.rb']
+end

data/lib/win32/semaphore.rb

@@ -0,0 +1,135 @@
+require 'win32/ipc'
+
+module Win32
+   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
+      
+      VERSION = '0.3.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
+         
+         # 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
+      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.
+      #--
+      # The OpenSemaphore() call here is strictly to force an error if the user
+      # tries to open a semaphore that doesn't already exist.
+      #
+      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
+         handle = OpenSemaphore(EVENT_ALL_ACCESS, bool, name)
+         if handle == 0 || handle == INVALID_HANDLE_VALUE
+            raise Error, get_last_error
+         end
+         CloseHandle(handle)
+
+         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 a Semaphore::Error is raised.
+      #
+      def release(amount = 1)
+         pcount = [0].pack('L')
+         unless ReleaseSemaphore(@handle, amount, pcount)
+            raise Error, get_last_error   
+         end
+         pcount.unpack('L').first
+      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/tc_semaphore.rb

@@ -0,0 +1,70 @@
+################################################################
+# tc_semaphore.rb
+#
+# Test suite for the win32-semaphore package. This test should
+# be run via the 'rake test' task.
+################################################################
+require 'win32/semaphore'
+require 'test/unit'
+include Win32
+
+class TC_Semaphore < Test::Unit::TestCase
+   def setup
+      @sem = Semaphore.new(1, 3, 'test')
+   end
+   
+   def test_version
+      assert_equal('0.3.0', Semaphore::VERSION)
+   end
+   
+   def test_max_semaphore_name
+      name = "foobar" * 500
+      assert_raises(Semaphore::Error){ Semaphore.new(1, 1, name){} }
+   end
+   
+   def test_open
+      assert_respond_to(Semaphore, :open)
+      assert_nothing_raised{ Semaphore.open('test'){} }
+      assert_raises(Semaphore::Error){ Semaphore.open('bogus'){} }
+   end
+   
+   def test_inheritable
+      assert_respond_to(@sem, :inheritable?)
+      assert_equal(true, @sem.inheritable?)
+   end
+   
+   def test_release
+      assert_respond_to(@sem, :release)
+      assert_equal(1, @sem.release(1))
+      assert_equal(2, @sem.release(1))
+      assert_raises(Semaphore::Error){ @sem.release(99) }
+   end
+   
+   def test_wait
+      assert_respond_to(@sem, :wait)
+   end
+   
+   def test_wait_any
+      assert_respond_to(@sem, :wait_any)
+   end
+   
+   def test_wait_all
+      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){} }
+   end
+   
+   def test_invalid_constructor
+      assert_raises(TypeError){ Semaphore.new("foo", "bar"){} }
+      assert_raises(ArgumentError){ Semaphore.new(1, 1, "test", 1, 1){} }      
+   end
+   
+   def teardown
+      @sem.close
+      @sem = nil
+   end
+end

data/win32-semaphore.gemspec

@@ -0,0 +1,24 @@
+require "rubygems"
+
+spec = Gem::Specification.new do |gem|
+   gem.name        = "win32-semaphore"
+   gem.version     = "0.3.0"
+   gem.author      = "Daniel J. Berger"
+   gem.email       = "djberg96@gmail.com"
+   gem.homepage    = "http://www.rubyforge.org/projects/win32utils"
+   gem.platform    = Gem::Platform::RUBY
+   gem.summary     = "Interface to MS Windows Semaphore objects."
+   gem.description = "Interface to MS Windows Semaphore objects."
+   gem.test_file   = "test/tc_semaphore.rb"
+   gem.has_rdoc    = true
+   gem.files       = Dir["lib/win32/*.rb"] + Dir["test/*"] + Dir["[A-Z]*"]
+   gem.files.reject! { |fn| fn.include? "CVS" }
+   gem.require_path = "lib"
+   gem.extra_rdoc_files = ["README", "CHANGES", "MANIFEST"]
+   gem.add_dependency("win32-ipc", ">= 0.5.0")
+end
+
+if $0 == __FILE__
+   Gem.manage_gems
+   Gem::Builder.new(spec).build
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.9.2
+specification_version: 1
+name: win32-semaphore
+version: !ruby/object:Gem::Version 
+  version: 0.3.0
+date: 2007-05-03 00:00:00 -06:00
+summary: Interface to MS Windows Semaphore objects.
+require_paths: 
+- lib
+email: djberg96@gmail.com
+homepage: http://www.rubyforge.org/projects/win32utils
+rubyforge_project: 
+description: Interface to MS Windows Semaphore objects.
+autorequire: 
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+post_install_message: 
+authors: 
+- Daniel J. Berger
+files: 
+- lib/win32/semaphore.rb
+- test/CVS
+- test/tc_semaphore.rb
+- CHANGES
+- CVS
+- doc
+- examples
+- lib
+- MANIFEST
+- Rakefile
+- README
+- test
+- win32-semaphore.gemspec
+test_files: 
+- test/tc_semaphore.rb
+rdoc_options: []
+
+extra_rdoc_files: 
+- README
+- CHANGES
+- MANIFEST
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: win32-ipc
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Version::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.5.0
+    version: