Class: Concurrent::Event — Concurrent Ruby

# Class: Concurrent::Event

Inherits:
  Synchronization::LockableObject
  - Object
  - Synchronization::LockableObject
  - Concurrent::Event
  show all

Defined in:
  lib/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 ocurred"
    end

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

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

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

See Also:

- http://msdn.microsoft.com/en-us/library/windows/desktop/ms682655.aspx

## Instance Method Summary collapse

- #initialize ⇒ Event constructor

  Creates a new `Event` in the unset state.

- #reset ⇒ Boolean

  Reset a previously set event back to the `unset` state.

- #set ⇒ Boolean

  Trigger the event, setting the state to `set` and releasing all threads waiting on the event.

- #set? ⇒ Boolean

  Is the object in the set state?.

- #try? ⇒ Boolean
- #wait(timeout = nil) ⇒ Boolean

  Wait a given number of seconds for the `Event` to be set by another thread.

## 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/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/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/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/atomic/event.rb', line 48

    def set?
      synchronize { @set }
    end

### #try? ⇒ `Boolean`

Returns:

- (`Boolean`)

    60
    61
    62
    # File 'lib/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/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