Module: Concurrent::Concern::Obligation — Concurrent Ruby

# Module: Concurrent::Concern::Obligation

Includes:
  Dereferenceable

Included in:
  Delay, IVar

Defined in:
  lib/concurrent-ruby/concurrent/concern/obligation.rb

## Instance Method Summary collapse

- #complete? ⇒ Boolean

  Has the obligation completed processing?.

- #exception(*args) ⇒ undocumented
- #fulfilled? ⇒ Boolean (also: #realized?)

  Has the obligation been fulfilled?.

- #incomplete? ⇒ Boolean

  Is the obligation still awaiting completion of processing?.

- #pending? ⇒ Boolean

  Is obligation completion still pending?.

- #reason ⇒ Exception

  If an exception was raised during processing this will return the exception object.

- #rejected? ⇒ Boolean

  Has the obligation been rejected?.

- #state ⇒ Symbol

  The current state of the obligation.

- #unscheduled? ⇒ Boolean

  Is the obligation still unscheduled?.

- #value(timeout = nil) ⇒ Object

  The current value of the obligation.

- #value!(timeout = nil) ⇒ Object

  The current value of the obligation.

- #wait(timeout = nil) ⇒ Obligation

  Wait until obligation is complete or the timeout has been reached.

- #wait!(timeout = nil) ⇒ Obligation (also: #no_error!)

  Wait until obligation is complete or the timeout is reached.

## Instance Method Details

### #complete? ⇒ `Boolean`

Has the obligation completed processing?

Returns:

- (`Boolean`)

    49
    50
    51
    # File 'lib/concurrent-ruby/concurrent/concern/obligation.rb', line 49

    def complete?
      [:fulfilled, :rejected].include? state
    end

### #exception(*args) ⇒ `undocumented`

Examples:

allows Obligation to be risen

    rejected_ivar = Ivar.new.fail
    raise rejected_ivar

    126
    127
    128
    129
    # File 'lib/concurrent-ruby/concurrent/concern/obligation.rb', line 126

    def exception(*args)
      raise 'obligation is not rejected' unless rejected?
      reason.exception(*args)
    end

### #fulfilled? ⇒ `Boolean` Also known as: realized?

Has the obligation been fulfilled?

Returns:

- (`Boolean`)

    20
    21
    22
    # File 'lib/concurrent-ruby/concurrent/concern/obligation.rb', line 20

    def fulfilled?
      state == :fulfilled
    end

### #incomplete? ⇒ `Boolean`

Is the obligation still awaiting completion of processing?

Returns:

- (`Boolean`)

    56
    57
    58
    # File 'lib/concurrent-ruby/concurrent/concern/obligation.rb', line 56

    def incomplete?
      ! complete?
    end

### #pending? ⇒ `Boolean`

Is obligation completion still pending?

Returns:

- (`Boolean`)

    35
    36
    37
    # File 'lib/concurrent-ruby/concurrent/concern/obligation.rb', line 35

    def pending?
      state == :pending
    end

### #reason ⇒ `Exception`

If an exception was raised during processing this will return the exception object. Will return `nil` when the state is pending or if the obligation has been successfully fulfilled.

Returns:

- (`Exception`) —

  the exception raised during processing or `nil`

    119
    120
    121
    # File 'lib/concurrent-ruby/concurrent/concern/obligation.rb', line 119

    def reason
      synchronize { @reason }
    end

### #rejected? ⇒ `Boolean`

Has the obligation been rejected?

Returns:

- (`Boolean`)

    28
    29
    30
    # File 'lib/concurrent-ruby/concurrent/concern/obligation.rb', line 28

    def rejected?
      state == :rejected
    end

### #state ⇒ `Symbol`

The current state of the obligation.

Returns:

- (`Symbol`) —

  the current state

    110
    111
    112
    # File 'lib/concurrent-ruby/concurrent/concern/obligation.rb', line 110

    def state
      synchronize { @state }
    end

### #unscheduled? ⇒ `Boolean`

Is the obligation still unscheduled?

Returns:

- (`Boolean`)

    42
    43
    44
    # File 'lib/concurrent-ruby/concurrent/concern/obligation.rb', line 42

    def unscheduled?
      state == :unscheduled
    end

### #value(timeout = nil) ⇒ `Object`

The current value of the obligation. Will be `nil` while the state is pending or the operation has been rejected.

Parameters:

- timeout (`Numeric`) (defaults to: `nil`) —

  the maximum time in seconds to wait.

Returns:

- (`Object`) —

  see Dereferenceable#deref

    65
    66
    67
    68
    # File 'lib/concurrent-ruby/concurrent/concern/obligation.rb', line 65

    def value(timeout = nil)
      wait timeout
      deref
    end

### #value!(timeout = nil) ⇒ `Object`

The current value of the obligation. Will be `nil` while the state is pending or the operation has been rejected. Will re-raise any exceptions raised during processing (but will not raise an exception on timeout).

Parameters:

- timeout (`Numeric`) (defaults to: `nil`) —

  the maximum time in seconds to wait.

Returns:

- (`Object`) —

  see Dereferenceable#deref

Raises:

- (`Exception`) —

  raises the reason when rejected

    98
    99
    100
    101
    102
    103
    104
    105
    # File 'lib/concurrent-ruby/concurrent/concern/obligation.rb', line 98

    def value!(timeout = nil)
      wait(timeout)
      if rejected?
        raise self
      else
        deref
      end
    end

### #wait(timeout = nil) ⇒ `Obligation`

Wait until obligation is complete or the timeout has been reached.

Parameters:

- timeout (`Numeric`) (defaults to: `nil`) —

  the maximum time in seconds to wait.

Returns:

- (`Obligation`) —

  self

    74
    75
    76
    77
    # File 'lib/concurrent-ruby/concurrent/concern/obligation.rb', line 74

    def wait(timeout = nil)
      event.wait(timeout) if timeout != 0 && incomplete?
      self
    end

### #wait!(timeout = nil) ⇒ `Obligation` Also known as: no_error!

Wait until obligation is complete or the timeout is reached. Will re-raise any exceptions raised during processing (but will not raise an exception on timeout).

Parameters:

- timeout (`Numeric`) (defaults to: `nil`) —

  the maximum time in seconds to wait.

Returns:

- (`Obligation`) —

  self

Raises:

- (`Exception`) —

  raises the reason when rejected

    86
    87
    88
    # File 'lib/concurrent-ruby/concurrent/concern/obligation.rb', line 86

    def wait!(timeout = nil)
      wait(timeout).tap { raise self if rejected? }
    end