Class: Win32::Event

Inherits:
Ipc
  • Object
show all
Extended by:
Windows::Error, Windows::Handle, Windows::Synchronize
Defined in:
lib/win32/event.rb

Defined Under Namespace

Classes: Error

Constant Summary collapse

VERSION = 
'0.5.0'

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name = nil, man_reset = false, init_state = false, inherit = true) ⇒ Event

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.



51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/win32/event.rb', line 51

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

Instance Attribute Details

#initial_state ⇒ Object (readonly)

The initial state of the Event object. If true, the initial state is signaled. Otherwise, it is non-signaled.



27
28
29
 
# File 'lib/win32/event.rb', line 27

def initial_state
  @initial_state
end

#manual_reset ⇒ Object (readonly)

Indicates whether or not the Event requires use of the ResetEvent() function set the state to nonsignaled.



22
23
24
 
# File 'lib/win32/event.rb', line 22

def manual_reset
  @manual_reset
end

#name ⇒ Object (readonly)

The name of the Event object.



17
18
19
 
# File 'lib/win32/event.rb', line 17

def name
  @name
end

Class Method Details

.open(name, inherit = true, &block) ⇒ Object

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.



105
106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/win32/event.rb', line 105

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

Instance Method Details

#inheritable? ⇒ Boolean

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.

Returns:

  • (Boolean) 


124
125
126
 
# File 'lib/win32/event.rb', line 124

def inheritable?
   @inherit
end

#reset ⇒ Object

Sets the Event object to a non-signaled state.



130
131
132
133
134
135
 
# File 'lib/win32/event.rb', line 130

def reset
   unless ResetEvent(@handle)
      raise Error, get_last_error
   end
   @signaled = false
end

#set ⇒ Object

Sets the Event object to a signaled state.



139
140
141
142
143
144
 
# File 'lib/win32/event.rb', line 139

def set
   unless SetEvent(@handle)
      raise Error, get_last_error
   end
   @signaled = true
end

#signaled=(bool) ⇒ Object

Synonym for Event#reset if bool is false, or Event#set if bool is true.



149
150
151
152
153
154
155
 
# File 'lib/win32/event.rb', line 149

def signaled=(bool)
   if bool
      set
   else
      reset
   end
end