win32-event 0.5.0

data/CHANGES

@@ -0,0 +1,40 @@
+== 0.5.0 - 3-May-2007
+* Now pure Ruby.
+* Both the Event.new and Event.close methods now accept a block, and
+  automatically close the associated handle at the end of the block.
+* The Event.new method now accepts an optional fourth argument that controls
+  whether the Event object can be inherited by other processes.
+* Added a gemspec.
+* Added a Rakefile, including tasks for installation and testing.
+* Removed the doc/event.txt file. The documentation is now inlined via RDoc.
+  There is also some documentation in the README file.
+* Now requires the windows-pr package.
+
+== 0.4.0 - 28-May-2005
+* All methods now return self or klass (instead of true).
+* Added the Event#inheritable? attribute that stores whether or not the Event
+  object is inheritable with regards to CreateProcess().
+* The Event#set and Event#unset now properly set the Event#signaled? value.
+* More Unicode friendly.
+* Removed the event.rd file.  The event.txt file is now rdoc friendly.
+* Code cleanup.
+
+== 0.3.1 - 1-Mar-2005
+* Moved the 'examples' directory to the toplevel directory.
+* Made the CHANGES and README files rdoc friendly.
+
+== 0.3.0 - 17-Jul-2004
+* Now uses the newer allocation framework, as well as replace the deprecated
+  STR2CSTR() function with StringValuePtr().  This means that, as of this
+  release, Ruby 1.8.0 or later is required.
+* Removed the .html file as part of the distro.  You can generate this on your
+  own via rd2.
+* Moved the test.rb script to doc/examples.
+
+== 0.2.0 - 28-Apr-2004
+* The Event class is now a subclass of Ipc (and thus requires the win32-ipc
+  package).
+* Documentation updates
+
+== 0.1.0 - 12-Jan-2004
+- Initial release.

data/MANIFEST

@@ -0,0 +1,7 @@
+* CHANGES
+* MANIFEST
+* README
+* Rakefile
+* win32-event.gemspec
+* lib/win32/event.rb
+* test/tc_event.rb

data/README

@@ -0,0 +1,52 @@
+== Description
+   Interface to MS Windows Event objects.
+
+== Prerequsites
+   Requires the win32-ipc package.
+   
+== Installation
+   rake test (optional)
+   rake install
+
+== Synopsis
+   Win32::Event.new("Foo") do |event|
+      event.set
+      # Do stuff
+      event.reset
+   end
+
+   e2 = Win32::Event.open("Bar")
+   # Do stuff
+   e2.close
+
+== Documentation
+   The event.rb file contains inline RDoc documentation. If you installed
+   this file as a gem, then you have the docs.
+
+== Notes
+   The Event 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).
+
+   A PulseEvent() wrapper is intentionally omitted.  From the MSDN web site:
+   "This function is unreliable and should not be used. It exists mainly for
+   backward compatibility."
+
+== Acknowledgements
+   The Win32::Event Perl module by Chris Madsen was used as a general
+   guideline for developing the API.
+    
+== Known Bugs
+   None that I'm aware of. Please submit any bug reports to the project page
+   at http://www.rubyforge.org/projects/win32utils.
+
+== Copyright
+   (C) 2003-2007 Daniel J. Berger
+   All Rights Reserved
+
+== License
+   Ruby's
+
+== Author
+   Park Heesob
+   Daniel J. Berger

data/Rakefile

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

data/lib/win32/event.rb

@@ -0,0 +1,157 @@
+require 'win32/ipc'
+
+module Win32
+   class Event < Ipc
+   
+      # This is the error raised if any of the Event methods fail.
+      class Error < StandardError; end
+      
+      extend Windows::Synchronize
+      extend Windows::Error
+      extend Windows::Handle
+      
+      VERSION = '0.5.0'
+   
+      # The name of the Event object.
+      #
+      attr_reader :name
+      
+      # Indicates whether or not the Event requires use of the ResetEvent()
+      # function set the state to nonsignaled.
+      #
+      attr_reader :manual_reset
+      
+      # The initial state of the Event object. If true, the initial state
+      # is signaled. Otherwise, it is non-signaled.
+      #
+      attr_reader :initial_state
+      
+      # Creates and returns new Event object.  If +name+ is omitted, the
+      # Event 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 +manual_reset+ and +initial_state+ parameters are
+      # ignored.
+      #
+      # If the +man_reset+ parameter is set to +true+, then it creates an Event
+      # object which requires use of the Event#reset method in order to set the
+      # state to non-signaled. If this parameter is false (the default) then
+      # the system automatically resets the state to non-signaled after a
+      # single waiting thread has been released.
+      #
+      # If the +init_state+ parameter is +true+, the initial state of the
+      # Event object is signaled; otherwise, it is nonsignaled (the default).
+      #
+      # If the +inherit+ parameter is true, then processes created by this
+      # process will inherit the handle. Otherwise they will not.
+      # 
+      # In block form this will automatically close the Event object at the
+      # end of the block.
+      # 
+      def initialize(name=nil, man_reset=false, init_state=false, inherit=true)
+         @name          = name
+         @manual_reset  = man_reset
+         @initial_state = init_state
+         @inherit       = inherit
+         
+         manual_reset  = man_reset ? 1 : 0
+         initial_state = init_state ? 1 : 0
+         
+         # 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 = CreateEvent(sec, manual_reset, initial_state, 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 Event 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 Event.new, except that the
+      # options for manual_reset and initial_state cannot be set (since they
+      # are already set). Also, this method will raise an Event::Error if the
+      # event doesn't already exist.
+      #
+      # If you want "open or create" semantics, then use Event.new.
+      #--
+      # The OpenEvent() call here is strictly to force an error if the user
+      # tries to open an event 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 = OpenEvent(EVENT_ALL_ACCESS, bool, name)
+         if handle == 0 || handle == INVALID_HANDLE_VALUE
+            raise Error, get_last_error
+         end
+         CloseHandle(handle)
+
+         self.new(name, false, false, inherit, &block)
+      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
+      
+      # Sets the Event object to a non-signaled state.
+      # 
+      def reset
+         unless ResetEvent(@handle)
+            raise Error, get_last_error
+         end
+         @signaled = false
+      end
+      
+      # Sets the Event object to a signaled state.
+      # 
+      def set
+         unless SetEvent(@handle)
+            raise Error, get_last_error
+         end
+         @signaled = true
+      end
+      
+      # Synonym for Event#reset if +bool+ is false, or Event#set
+      # if +bool+ is true.
+      # 
+      def signaled=(bool)
+         if bool
+            set
+         else
+            reset
+         end
+      end 
+   end
+end

data/test/tc_event.rb

@@ -0,0 +1,121 @@
+#####################################################################
+# tc_event.rb
+#
+# Test suite for the win32-event package. This test should be run
+# via the 'rake test' task.
+#####################################################################
+require "test/unit"
+require "win32/event"
+include Win32
+
+class TC_Win32Event < Test::Unit::TestCase
+   def setup
+      @event1 = Event.new
+      @event2 = Event.new("Foo")
+      @event3 = Event.new("Bar", true)
+      @event4 = Event.new("Baz", true, true)
+      @uni_event = Event.new("Ηελλας")
+   end
+   
+   def test_version
+      assert_equal('0.5.0', Event::VERSION)
+   end
+  
+   def test_constructor_errors
+      assert_raises(ArgumentError){ Event.new("Foo", true, false, true, 1) }
+      assert_raises(TypeError){ Event.new(1) }
+   end
+   
+   def test_open
+      assert_respond_to(Event, :open)
+      assert_nothing_raised{ Event.open("Bar"){} }
+      assert_nothing_raised{ Event.open("Ηελλας"){} }
+      assert_nothing_raised{ Event.open("Bar", false) }
+      
+      assert_raises(ArgumentError){ Event.open("Bar", true, false){} }
+      assert_raises(Event::Error){ Event.open("Blah"){} }
+      assert_raises(TypeError){ Event.open(1){} }
+   end
+   
+   def test_inheritable
+      @event1 = Event.open("Foo")
+      @event2 = Event.open("Baz", false)
+      
+      assert_respond_to(@event1, :inheritable?)
+      assert_nothing_raised{ @event1.inheritable? }
+      
+      assert_equal(true, @event1.inheritable?)
+      assert_equal(false, @event2.inheritable?)
+   end
+   
+   def test_name
+      assert_respond_to(@event1, :name)
+      assert_nothing_raised{ @event1.name }
+      assert_nothing_raised{ @uni_event.name }
+      
+      assert_nil(@event1.name)
+      assert_kind_of(String, @event2.name)
+   end
+   
+   def test_initial_state
+      assert_respond_to(@event1, :initial_state)
+      assert_nothing_raised{ @event1.initial_state }
+      
+      assert_equal(false, @event1.initial_state)
+      assert_equal(false, @event2.initial_state)
+      assert_equal(false, @event3.initial_state)
+      assert_equal(true, @event4.initial_state)
+   end
+   
+   def test_manual_reset
+      assert_respond_to(@event1, :manual_reset)
+      assert_nothing_raised{ @event1.manual_reset }
+      
+      assert_equal(false, @event1.manual_reset)
+      assert_equal(false, @event2.manual_reset)
+      assert_equal(true, @event3.manual_reset)
+      assert_equal(true, @event4.manual_reset)
+   end
+   
+   def test_set
+      assert_respond_to(@event1, :set)
+      assert_nothing_raised{ @event1.set }
+   end
+   
+   def test_is_signaled
+      event = Event.new
+      assert_respond_to(event, :signaled?)
+      assert_nothing_raised{ event.signaled? }
+      
+      assert_equal(false, event.signaled?)
+      event.set
+      assert_equal(true, event.signaled?)
+      event.reset
+      assert_equal(false, event.signaled?)
+   end
+   
+   def test_reset
+      assert_respond_to(@event1, :reset)
+      assert_nothing_raised{ @event1.reset }
+   end
+   
+   def test_close
+      event = Event.new
+      assert_respond_to(event, :close)
+      assert_nothing_raised{ event.close }
+   end
+   
+   def teardown
+      @event1.close
+      @event2.close
+      @event3.close
+      @event4.close
+      @uni_event.close
+      
+      @event1 = nil
+      @event2 = nil
+      @event3 = nil
+      @event4 = nil
+      @uni_event = nil
+   end
+end

data/win32-event.gemspec

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