win32-mutex 0.3.0

data/CHANGES

@@ -0,0 +1,33 @@
+== 0.3.0 - 4-May-2007
+* Now pure Ruby.
+* Both the Mutex.new and Mutex.open methods now accept a block, and
+  automatically close the associated handle at the end of the block.
+* The Mutex.new method now accepts an optional third argument that controls
+  whether the mutex object can be inherited by other processes.
+* Added a gemspec.
+* Added a Rakefile, including tasks for installation and testing.
+* Removed the doc/mutext.txt file. The documentation is now inlined via RDoc.
+  There is also some documentation in the README file.
+* The mutex_test.rb script was updated and bugs were fixed.
+* Now requires the windows-pr package.
+
+== 0.2.2 - 29-May-2005
+* Now Unicode friendly.
+* Removed the mutex.rd file.  The mutex.txt file is now rdoc friendly.
+* Added some tests and tweaked the test setup.
+
+== 0.2.1 - 1-Mar-2005
+* Moved the 'examples' directory to the toplevel directory.
+* Made the CHANGES and README files rdoc friendly.
+
+== 0.2.0 - 18-Jul-2004
+* Updated to use the newer allocation framework.  This means that, as of this
+  release, this package requires Ruby 1.8.0 or later.
+* Fixed a minor bug in the initialization function where an expected error
+  might not be raised.
+* Added tests and documentation for Mutex.open().  This was in the last
+  version, but I forgot to document or test it.
+* Moved the test.rb script to doc/examples
+
+== 0.1.0 - 3-May-2004
+* Initial release

data/MANIFEST

@@ -0,0 +1,8 @@
+* CHANGES
+* INSTALL
+* MANIFEST
+* Rakefile
+* win32-mutex.gemspec
+* examples/mutex_test.rb
+* lib/win32/mutex.rb
+* test/tc_mutex.rb

data/README

@@ -0,0 +1,52 @@
+== Brief Description
+   Interface for Mutexes on MS Windows.
+
+== Prerequisites
+   win32-ipc 0.5.0 or later
+
+== Installation
+   rake test (optional)
+   rake install
+
+== Synopsis
+   require 'win32/mutex'
+
+   # Do not leave out the 'Win32::', otherwise you're using Ruby's Mutex class.
+   Win32::Mutex.new(false, 'test') do |m|
+      # Do stuff
+      m.release
+   end
+
+== Documentation
+   The mutex.rb file contains inline RDoc documentation. If you installed
+   this file as a gem, then you have the docs.
+
+   For an example of win32-mutex in action, look at the mutex_test.rb file
+   in the 'examples' directory. You can also run the 'examples' rake task.
+
+== Notes
+   The Mutex 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
+   Originally adapted from the Win32::Mutex Perl module.
+
+== Known Bugs  
+   None that I know of. Please log any other bug reports on the RubyForge
+   project page at http://www.rubyforge.net/projects/win32utils
+    
+== 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.
+
+== Authors
+   Daniel J. Berger
+   Park Heesob

data/Rakefile

@@ -0,0 +1,26 @@
+require 'rake'
+require 'rake/testtask'
+require 'rbconfig'
+include Config
+
+desc 'Install the win32-mutex package (non-gem)'
+task :install do
+   sitelibdir = CONFIG['sitelibdir']
+   installdir = File.join(sitelibdir, 'win32')
+   file = 'lib\win32\mutex.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/mutex_test.rb'
+end
+
+Rake::TestTask.new do |t|
+   t.libs << 'test'
+   t.verbose = true
+   t.warning = true
+   t.test_files = FileList['test/tc_mutex.rb']
+end

data/lib/win32/mutex.rb

@@ -0,0 +1,124 @@
+require 'win32/ipc'
+
+module Win32
+   class Mutex < Ipc
+   
+      # This is the error raised if any of the Mutex methods fail.
+      class Error < StandardError; end
+   
+      extend Windows::Synchronize
+      extend Windows::Error
+      extend Windows::Handle
+      
+      VERSION = '0.3.0'
+      
+      # The name of the Mutex object.
+      #
+      attr_reader :name
+      
+      # Creates and returns new Mutex object. If +name+ is omitted, the
+      # Mutex object is created without a name, i.e. it's anonymous.
+      #
+      # If the +initial_owner+ value is true and the caller created the mutex,
+      # the calling thread obtains initial ownership of the mutex object.
+      # Otherwise, the calling thread does not obtain ownership of the mutex.
+      # This value is false by default.
+      #
+      # If +name+ is provided and it already exists, then it is opened
+      # instead, and the +initial_count+ and +max_count+ parameters are
+      # ignored.
+      #
+      # The +inherit+ attribute determines whether or not the mutex can
+      # be inherited by child processes.
+      #
+      def initialize(initial_owner=false, name=nil, inherit=true)
+         @initial_owner = initial_owner
+         @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
+         
+         initial = initial_owner ? 1 : 0
+         
+         handle = CreateMutex(sec, initial, 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 Mutex 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 Mutex.new, except that the
+      # option for +initial_owner+ cannot be set (since it is already set).
+      # Also, this method will raise a Mutex::Error if the mutex doesn't
+      # already exist.
+      #
+      # If you want "open or create" semantics, then use Mutex.new.
+      #--
+      # The OpenMutex() call here is strictly to force an error if the user
+      # tries to open a mutex 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 = OpenMutex(MUTEX_ALL_ACCESS, bool, name)
+         if handle == 0 || handle == INVALID_HANDLE_VALUE
+            raise Error, get_last_error
+         end
+         CloseHandle(handle)
+
+         self.new(false, name, inherit, &block)
+      end
+
+      # Releases ownership of the mutex.
+      #
+      def release
+         unless ReleaseMutex(@handle)
+            raise Error, get_last_error   
+         end
+      end
+      
+      # Returns whether or not the calling thread has initial ownership of
+      # the mutex object.
+      #
+      def initial_owner?
+         @initial_owner
+      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_mutex.rb

@@ -0,0 +1,61 @@
+#####################################################################
+# tc_Win32::Mutex.rb
+#
+# Test suite for the win32-Win32::Mutex package. This test suite should
+# be run via the 'rake test' task.
+#####################################################################
+require 'test/unit'
+require 'win32/mutex'
+
+class TC_Win32_Mutex < Test::Unit::TestCase
+	def setup
+		@mutex  = Win32::Mutex.new(true, 'test')
+		@umutex = Win32::Mutex.new(false, "Ηελλας")
+	end
+	
+	def test_version
+		assert_equal('0.3.0', Win32::Mutex::VERSION)
+	end
+
+	def test_open
+	   assert_respond_to(Win32::Mutex, :open)
+	   assert_nothing_raised{ Win32::Mutex.open("test"){} }
+	   assert_nothing_raised{ Win32::Mutex.open("Ηελλας"){} }
+	   assert_raises(Win32::Mutex::Error){ Win32::Mutex.open("bogus"){} }
+	end
+	
+	def test_release
+		assert_respond_to(@mutex, :release)
+      assert_nothing_raised{ @mutex.release }
+	end
+   
+   def test_initial_owner
+      assert_respond_to(@mutex, :initial_owner?)
+      assert_equal(true, @mutex.initial_owner?)
+      assert_equal(false, @umutex.initial_owner?)
+   end
+   
+   def test_inheritable
+      assert_respond_to(@mutex, :inheritable?)
+      assert_equal(true, @mutex.inheritable?)
+   end
+	
+	def test_wait
+		assert_respond_to(@mutex, :wait)
+	end
+	
+	def test_wait_any
+		assert_respond_to(@mutex, :wait_any)
+	end
+	
+	def test_wait_all
+		assert_respond_to(@mutex, :wait_all)
+	end
+   
+	def teardown
+      @mutex.close
+      @umutex.close
+		@mutex = nil
+		@umutex = nil
+	end
+end

data/win32-mutex.gemspec

@@ -0,0 +1,24 @@
+require "rubygems"
+
+spec = Gem::Specification.new do |gem|
+   gem.name        = "win32-mutex"
+   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 Mutex objects."
+   gem.description = "Interface to MS Windows Mutex objects."
+   gem.test_file   = "test/tc_mutex.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,67 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.9.2
+specification_version: 1
+name: win32-mutex
+version: !ruby/object:Gem::Version 
+  version: 0.3.0
+date: 2007-05-04 00:00:00 -06:00
+summary: Interface to MS Windows Mutex objects.
+require_paths: 
+- lib
+email: djberg96@gmail.com
+homepage: http://www.rubyforge.org/projects/win32utils
+rubyforge_project: 
+description: Interface to MS Windows Mutex 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/mutex.rb
+- test/CVS
+- test/tc_mutex.rb
+- CHANGES
+- CVS
+- examples
+- lib
+- MANIFEST
+- Rakefile
+- README
+- test
+- win32-mutex.gemspec
+test_files: 
+- test/tc_mutex.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: