Class: Win32::Event
- Inherits:
-
Ipc
- Object
- Ipc
- Win32::Event
- Defined in:
- lib/win32/event.rb
Overview
The Event class encapsulates Windows event objects.
Defined Under Namespace
Classes: Error, SecurityAttributes
Constant Summary collapse
- INVALID_HANDLE_VALUE =
0xFFFFFFFF
- EVENT_ALL_ACCESS =
0x1F0003
- VERSION =
The version of the win32-event library
'0.6.1'
Instance Attribute Summary collapse
-
#initial_state ⇒ Object
readonly
The initial state of the Event object.
-
#manual_reset ⇒ Object
readonly
Indicates whether or not the Event requires use of the ResetEvent() function set the state to nonsignaled.
-
#name ⇒ Object
readonly
The name of the Event object.
Class Method Summary collapse
-
.open(name, inherit = true, &block) ⇒ Object
Open an existing Event by
name
.
Instance Method Summary collapse
-
#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.
-
#initialize(name = nil, man_reset = false, init_state = false, inherit = true) ⇒ Event
constructor
Creates and returns new Event object.
-
#reset ⇒ Object
Sets the Event object to a non-signaled state.
-
#set ⇒ Object
Sets the Event object to a signaled state.
-
#signaled=(bool) ⇒ Object
Synonym for Event#reset if
bool
is false, or Event#set ifbool
is true.
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.
73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 |
# File 'lib/win32/event.rb', line 73 def initialize(name=nil, man_reset=false, init_state=false, inherit=true) @name = name @manual_reset = man_reset @initial_state = init_state @inherit = inherit if name.is_a?(String) if name.encoding.to_s != 'UTF-16LE' name = name + 0.chr name.encode!('UTF-16LE') end else raise TypeError if name end if inherit sec = SecurityAttributes.new sec[:nLength] = SecurityAttributes.size sec[:bInheritHandle] = inherit else sec = nil end handle = CreateEvent(sec, manual_reset, initial_state, name) if handle == 0 || handle == INVALID_HANDLE_VALUE raise SystemCallError.new("CreateEvent", FFI.errno) end super(handle) 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. The default is false.
49 50 51 |
# File 'lib/win32/event.rb', line 49 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. The default is false
44 45 46 |
# File 'lib/win32/event.rb', line 44 def manual_reset @manual_reset end |
#name ⇒ Object (readonly)
The name of the Event object. The default is nil
39 40 41 |
# File 'lib/win32/event.rb', line 39 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.
117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 |
# File 'lib/win32/event.rb', line 117 def self.open(name, inherit=true, &block) raise TypeError unless name.is_a?(String) if name.encoding.to_s != 'UTF-16LE' oname = name + 0.chr oname.encode!('UTF-16LE') else oname = name.dup end # This block of code is here strictly to force an error if the user # tries to open an event that doesn't already exist. begin h = OpenEvent(EVENT_ALL_ACCESS, inherit, oname) if h == 0 || h == INVALID_HANDLE_VALUE raise SystemCallError.new("OpenEvent", FFI.errno) end ensure CloseHandle(h) if h end 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.
146 147 148 |
# File 'lib/win32/event.rb', line 146 def inheritable? @inherit end |
#reset ⇒ Object
Sets the Event object to a non-signaled state.
152 153 154 155 156 157 |
# File 'lib/win32/event.rb', line 152 def reset unless ResetEvent(@handle) raise SystemCallError.new("ResetEvent", FFI.errno) end @signaled = false end |
#set ⇒ Object
Sets the Event object to a signaled state.
161 162 163 164 165 166 |
# File 'lib/win32/event.rb', line 161 def set unless SetEvent(@handle) raise SystemCallError.new("SetEvent", FFI.errno) end @signaled = true end |
#signaled=(bool) ⇒ Object
Synonym for Event#reset if bool
is false, or Event#set if bool
is true.
171 172 173 174 175 176 177 |
# File 'lib/win32/event.rb', line 171 def signaled=(bool) if bool set else reset end end |