Class: Win32::Event

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

Overview

The Event class encapsulates Windows event objects.

Defined Under Namespace

Classes: Error

Constant Summary collapse

VERSION =

The version of the win32-event library

'0.5.2'

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.



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

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.



31
32
33
 
# File 'lib/win32/event.rb', line 31

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.



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

def manual_reset
  @manual_reset
end

#name ⇒ Object (readonly)

The name of the Event object.



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

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.



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

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

  # 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
    handle = OpenEvent(EVENT_ALL_ACCESS, bool, name)

    if handle == 0 || handle == INVALID_HANDLE_VALUE
      raise Error, get_last_error
    end
  ensure
    CloseHandle(handle) if handle > 0
  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) 


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

def inheritable?
  @inherit
end

#reset ⇒ Object

Sets the Event object to a non-signaled state.



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

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

#set ⇒ Object

Sets the Event object to a signaled state.



147
148
149
150
151
152
 
# File 'lib/win32/event.rb', line 147

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.



157
158
159
160
161
162
163
 
# File 'lib/win32/event.rb', line 157

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