Class: Win32::Event

Inherits:
Ipc
  • Object
show all
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.3'

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name = nil, manual_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.



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
89
90
91
92
93
 
# File 'lib/win32/event.rb', line 63

def initialize(name=nil, manual_reset=false, init_state=false, inherit=true)
  @name          = name
  @manual_reset  = manual_reset ? 1 : 0
  @initial_state = init_state ? 1 : 0
  @inherit       = inherit ? 1 : 0

  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

#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.

Raises:

  • (TypeError) 


107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/win32/event.rb', line 107

def self.open(name, inherit=true, &block)
  raise TypeError unless name.is_a?(String)

  inheritable = inherit ? 1 : 0

  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, inheritable, 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.

Returns:

  • (Boolean) 


156
157
158
 
# File 'lib/win32/event.rb', line 156

def inheritable?
  [1, true].include?(@inherit)
end

#initial_state ⇒ Object Also known as: initial_state?

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



146
147
148
 
# File 'lib/win32/event.rb', line 146

def initial_state
  [1, true].include?(@initial_state)
end

#manual_reset ⇒ Object Also known as: manual_reset?

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



137
138
139
 
# File 'lib/win32/event.rb', line 137

def manual_reset
  [1, true].include?(@manual_reset)
end

#reset ⇒ Object

Sets the Event object to a non-signaled state.



162
163
164
165
166
167
 
# File 'lib/win32/event.rb', line 162

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.



171
172
173
174
175
176
 
# File 'lib/win32/event.rb', line 171

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.



181
182
183
184
185
186
187
 
# File 'lib/win32/event.rb', line 181

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