Class: Concurrent::Promises::ResolvableFuture

Inherits:
Future
  • Object
show all
Includes:
Resolvable
Defined in:
lib/concurrent-ruby/concurrent/promises.rb

Overview

A Future which can be resolved by user.

Instance Method Summary collapse

Instance Method Details

#evaluate_to(*args) {|*args| ... } ⇒ self

Evaluates the block and sets its result as future's value fulfilling, if the block raises an exception the future rejects with it.

Yields:

  • (*args) —

    to the block.

Yield Returns:

  • (Object) —

    value

Returns:

  • (self) 


1401
1402
1403
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1401

def evaluate_to(*args, &block)
  promise.evaluate_to(*args, block)
end

#evaluate_to!(*args) {|*args| ... } ⇒ self

Evaluates the block and sets its result as future's value fulfilling, if the block raises an exception the future rejects with it.

Yields:

  • (*args) —

    to the block.

Yield Returns:

  • (Object) —

    value

Returns:

  • (self)

Raises:

  • (Exception) —

    also raise reason on rejection.



1412
1413
1414
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1412

def evaluate_to!(*args, &block)
  promise.evaluate_to(*args, block).wait!
end

#fulfill(value, raise_on_reassign = true, reserved = false) ⇒ self, false

Makes the future fulfilled with value, which triggers all dependent futures.

Parameters:

  • value (Object)
  • raise_on_reassign (Boolean) (defaults to: true) —

    should method raise exception if already resolved

  • reserved (true, false) (defaults to: false) —

    Set to true if the resolvable is Concurrent::Promises::Resolvable#reserved by you, marks resolution of reserved resolvable events and futures explicitly. Advanced feature, ignore unless you use Concurrent::Promises::Resolvable#reserve from edge.

Returns:

  • (self, false) —

    false is returned when raise_on_reassign is false and the receiver is already resolved.



1381
1382
1383
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1381

def fulfill(value, raise_on_reassign = true, reserved = false)
  resolve_with Fulfilled.new(value), raise_on_reassign, reserved
end

#reason(timeout = nil, timeout_value = nil, resolve_on_timeout = nil) ⇒ Exception, timeout_value, nil

Behaves as Future#reason but has one additional optional argument resolve_on_timeout.

Parameters:

  • resolve_on_timeout (::Array(true, Object, nil), ::Array(false, nil, Exception), nil) (defaults to: nil) —

    If it times out and the argument is not nil it will also resolve the future to the provided resolution.

Returns:

  • (Exception, timeout_value, nil)

See Also:



1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1509

def reason(timeout = nil, timeout_value = nil, resolve_on_timeout = nil)
  if wait_until_resolved timeout
    internal_state.reason
  else
    if resolve_on_timeout
      unless resolve(*resolve_on_timeout, false)
        # if it fails to resolve it was resolved in the meantime
        # so return value as if there was no timeout
        return internal_state.reason
      end
    end
    timeout_value
  end
end

#reject(reason, raise_on_reassign = true, reserved = false) ⇒ self, false

Makes the future rejected with reason, which triggers all dependent futures.

Parameters:

  • reason (Object)
  • raise_on_reassign (Boolean) (defaults to: true) —

    should method raise exception if already resolved

  • reserved (true, false) (defaults to: false) —

    Set to true if the resolvable is Concurrent::Promises::Resolvable#reserved by you, marks resolution of reserved resolvable events and futures explicitly. Advanced feature, ignore unless you use Concurrent::Promises::Resolvable#reserve from edge.

Returns:

  • (self, false) —

    false is returned when raise_on_reassign is false and the receiver is already resolved.



1391
1392
1393
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1391

def reject(reason, raise_on_reassign = true, reserved = false)
  resolve_with Rejected.new(reason), raise_on_reassign, reserved
end

#resolve(fulfilled = true, value = nil, reason = nil, raise_on_reassign = true, reserved = false) ⇒ self, false

Makes the future resolved with result of triplet fulfilled?, value, reason, which triggers all dependent futures.

Parameters:

  • fulfilled (true, false) (defaults to: true)
  • value (Object) (defaults to: nil)
  • reason (Object) (defaults to: nil)
  • raise_on_reassign (Boolean) (defaults to: true) —

    should method raise exception if already resolved

  • reserved (true, false) (defaults to: false) —

    Set to true if the resolvable is Concurrent::Promises::Resolvable#reserved by you, marks resolution of reserved resolvable events and futures explicitly. Advanced feature, ignore unless you use Concurrent::Promises::Resolvable#reserve from edge.

Returns:

  • (self, false) —

    false is returned when raise_on_reassign is false and the receiver is already resolved.



1371
1372
1373
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1371

def resolve(fulfilled = true, value = nil, reason = nil, raise_on_reassign = true, reserved = false)
  resolve_with(fulfilled ? Fulfilled.new(value) : Rejected.new(reason), raise_on_reassign, reserved)
end

#result(timeout = nil, resolve_on_timeout = nil) ⇒ ::Array(Boolean, Object, Exception), nil

Behaves as Future#result but has one additional optional argument resolve_on_timeout.

Parameters:

  • resolve_on_timeout (::Array(true, Object, nil), ::Array(false, nil, Exception), nil) (defaults to: nil) —

    If it times out and the argument is not nil it will also resolve the future to the provided resolution.

Returns:

  • (::Array(Boolean, Object, Exception), nil)

See Also:



1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1530

def result(timeout = nil, resolve_on_timeout = nil)
  if wait_until_resolved timeout
    internal_state.result
  else
    if resolve_on_timeout
      unless resolve(*resolve_on_timeout, false)
        # if it fails to resolve it was resolved in the meantime
        # so return value as if there was no timeout
        internal_state.result
      end
    end
    # otherwise returns nil
  end
end

#value(timeout = nil, timeout_value = nil, resolve_on_timeout = nil) ⇒ Object, timeout_value, nil

Behaves as Future#value but has one additional optional argument resolve_on_timeout.

Parameters:

  • resolve_on_timeout (::Array(true, Object, nil), ::Array(false, nil, Exception), nil) (defaults to: nil) —

    If it times out and the argument is not nil it will also resolve the future to the provided resolution.

Returns:

  • (Object, timeout_value, nil)

See Also:



1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1465

def value(timeout = nil, timeout_value = nil, resolve_on_timeout = nil)
  if wait_until_resolved timeout
    internal_state.value
  else
    if resolve_on_timeout
      unless resolve(*resolve_on_timeout, false)
        # if it fails to resolve it was resolved in the meantime
        # so return value as if there was no timeout
        return internal_state.value
      end
    end
    timeout_value
  end
end

#value!(timeout = nil, timeout_value = nil, resolve_on_timeout = nil) ⇒ Object, timeout_value, nil

Behaves as Future#value! but has one additional optional argument resolve_on_timeout.

Parameters:

  • resolve_on_timeout (::Array(true, Object, nil), ::Array(false, nil, Exception), nil) (defaults to: nil) —

    If it times out and the argument is not nil it will also resolve the future to the provided resolution.

Returns:

  • (Object, timeout_value, nil)

Raises:

  • (Exception) —

    #reason on rejection

See Also:



1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1487

def value!(timeout = nil, timeout_value = nil, resolve_on_timeout = nil)
  if wait_until_resolved! timeout
    internal_state.value
  else
    if resolve_on_timeout
      unless resolve(*resolve_on_timeout, false)
        # if it fails to resolve it was resolved in the meantime
        # so return value as if there was no timeout
        raise self if rejected?
        return internal_state.value
      end
    end
    timeout_value
  end
end

#wait(timeout = nil, resolve_on_timeout = nil) ⇒ self, true, false

Behaves as AbstractEventFuture#wait but has one additional optional argument resolve_on_timeout.

Parameters:

  • resolve_on_timeout (::Array(true, Object, nil), ::Array(false, nil, Exception), nil) (defaults to: nil) —

    If it times out and the argument is not nil it will also resolve the future to the provided resolution.

Returns:

  • (self, true, false)

See Also:



1427
1428
1429
1430
1431
1432
1433
1434
1435
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1427

def wait(timeout = nil, resolve_on_timeout = nil)
  super(timeout) or if resolve_on_timeout
                      # if it fails to resolve it was resolved in the meantime
                      # so return true as if there was no timeout
                      !resolve(*resolve_on_timeout, false)
                    else
                      false
                    end
end

#wait!(timeout = nil, resolve_on_timeout = nil) ⇒ self, true, false

Behaves as Future#wait! but has one additional optional argument resolve_on_timeout.

Parameters:

  • resolve_on_timeout (::Array(true, Object, nil), ::Array(false, nil, Exception), nil) (defaults to: nil) —

    If it times out and the argument is not nil it will also resolve the future to the provided resolution.

Returns:

  • (self, true, false)

Raises:

  • (Exception) —

    #reason on rejection

See Also:



1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1444

def wait!(timeout = nil, resolve_on_timeout = nil)
  super(timeout) or if resolve_on_timeout
                      if resolve(*resolve_on_timeout, false)
                        false
                      else
                        # if it fails to resolve it was resolved in the meantime
                        # so return true as if there was no timeout
                        raise self if rejected?
                        true
                      end
                    else
                      false
                    end
end

#with_hidden_resolvable ⇒ Future

Creates new future wrapping receiver, effectively hiding the resolve method and similar.

Returns:



1548
1549
1550
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1548

def with_hidden_resolvable
  @with_hidden_resolvable ||= FutureWrapperPromise.new_blocked_by1(self, @DefaultExecutor).future
end

#release ⇒ true, false Originally defined in module Resolvable

Returns on successful release of the reservation.

Returns:

  • (true, false) —

    on successful release of the reservation

#reserve ⇒ true, false Originally defined in module Resolvable

Reserves the event or future, if reserved others are prevented from resolving it. Advanced feature. Be careful about the order of reservation to avoid deadlocks, the method blocks if the future or event is already reserved until it is released or resolved.

Examples:

f = Concurrent::Promises.resolvable_future
reserved = f.reserve
Thread.new { f.resolve true, :val, nil } # fails
f.resolve true, :val, nil, true if reserved # must be called only if reserved

Returns:

  • (true, false) —

    on successful reservation