Class: Concurrent::Event

Inherits:
Synchronization::LockableObject
  • Object
show all
Defined in:
lib/concurrent-ruby/concurrent/atomic/event.rb

Overview

Old school kernel-style event reminiscent of Win32 programming in C++.

When an ‘Event` is created it is in the `unset` state. Threads can choose to `#wait` on the event, blocking until released by another thread. When one thread wants to alert all blocking threads it calls the `#set` method which will then wake up all listeners. Once an `Event` has been set it remains set. New threads calling `#wait` will return immediately. An `Event` may be `#reset` at any time once it has been set.

Examples:

event = Concurrent::Event.new

t1 = Thread.new do
  puts "t1 is waiting"
  event.wait(1)
  puts "event occurred"
end

t2 = Thread.new do
  puts "t2 calling set"
  event.set
end

[t1, t2].each(&:join)

# prints:
# t1 is waiting
# t2 calling set
# event occurred

See Also:

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Event

Creates a new ‘Event` in the unset state. Threads calling `#wait` on the `Event` will block.



40
41
42
43
 
# File 'lib/concurrent-ruby/concurrent/atomic/event.rb', line 40

def initialize
  super
  synchronize { ns_initialize }
end

Instance Method Details

#reset ⇒ Boolean

Reset a previously set event back to the ‘unset` state. Has no effect if the `Event` has not yet been set.

Returns:

  • (Boolean) —

    should always return ‘true`



68
69
70
71
72
73
74
75
76
 
# File 'lib/concurrent-ruby/concurrent/atomic/event.rb', line 68

def reset
  synchronize do
    if @set
      @set       = false
      @iteration +=1
    end
    true
  end
end

#set ⇒ Boolean

Trigger the event, setting the state to ‘set` and releasing all threads waiting on the event. Has no effect if the `Event` has already been set.

Returns:

  • (Boolean) —

    should always return ‘true`



56
57
58
 
# File 'lib/concurrent-ruby/concurrent/atomic/event.rb', line 56

def set
  synchronize { ns_set }
end

#set? ⇒ Boolean

Is the object in the set state?

Returns:

  • (Boolean) —

    indicating whether or not the ‘Event` has been set



48
49
50
 
# File 'lib/concurrent-ruby/concurrent/atomic/event.rb', line 48

def set?
  synchronize { @set }
end

#try? ⇒ Boolean

Returns:

  • (Boolean) 


60
61
62
 
# File 'lib/concurrent-ruby/concurrent/atomic/event.rb', line 60

def try?
  synchronize { @set ? false : ns_set }
end

#wait(timeout = nil) ⇒ Boolean

Wait a given number of seconds for the ‘Event` to be set by another thread. Will wait forever when no `timeout` value is given. Returns immediately if the `Event` has already been set.

Returns:

  • (Boolean) —

    true if the ‘Event` was set before timeout else false



83
84
85
86
87
88
89
90
91
92
 
# File 'lib/concurrent-ruby/concurrent/atomic/event.rb', line 83

def wait(timeout = nil)
  synchronize do
    unless @set
      iteration = @iteration
      ns_wait_until(timeout) { iteration < @iteration || @set }
    else
      true
    end
  end
end