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.1'

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.



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.

Raises:

  • (TypeError) 


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.

Returns:

  • (Boolean) 


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