Module: Ione::Future::Combinators

Included in:
Ione::Future
Defined in:
lib/ione/future.rb

Overview

Since:

  • v1.0.0

Instance Method Summary collapse

Instance Method Details

#fallback {|error| ... } ⇒ Ione::Future

Returns a new future which represents either the value of the original future, or the value of the future returned by the given block.

This is like but for cases when the handling of an error is itself asynchronous. In other words, is to what is to .

If the block raises an error a failed future with that error will be returned (this can be used to transform an error into another error, instead of tranforming an error into a value).

Examples:

result = http_get('/foo/bar').fallback do |error|
  http_get('/baz')
end
result.value # either the response to /foo/bar, or if that failed
             # the response to /baz

Yield Parameters:

  • error (Object)

    the error from the original future

Yield Returns:

  • (Object)

    the value of the new future

Returns:

  • (Ione::Future)

    a new future representing a value recovered from the error

Since:

  • v1.0.0


542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
# File 'lib/ione/future.rb', line 542

def fallback(&block)
  f = CompletableFuture.new
  on_complete do |v, e|
    if e
      begin
        ff = block.call(e)
        ff.on_complete do |vv, ee|
          if ee
            f.fail(ee)
          else
            f.resolve(vv)
          end
        end
      rescue => e
        f.fail(e)
      end
    else
      f.resolve(v)
    end
  end
  f
end

#flat_map {|value| ... } ⇒ Ione::Future

Returns a new future representing a transformation of this future’s value, but where the transformation itself may be asynchronous.

This method is useful when you want to chain asynchronous operations.

Examples:

future2 = future1.flat_map { |value| method_returning_a_future(value) }

Yield Parameters:

  • value (Object)

    the value of this future

Yield Returns:

  • (Ione::Future)

    a future representing the transformed value

Returns:

  • (Ione::Future)

    a new future representing the transformed value

Since:

  • v1.0.0


411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
# File 'lib/ione/future.rb', line 411

def flat_map(&block)
  f = CompletableFuture.new
  on_complete do |v, e|
    if e
      f.fail(e)
    else
      begin
        ff = block.call(v)
        ff.on_complete do |vv, ee|
          if ee
            f.fail(ee)
          else
            f.resolve(vv)
          end
        end
      rescue => e
        f.fail(e)
      end
    end
  end
  f
end

#map(value = nil) {|value| ... } ⇒ Ione::Future

Returns a new future representing a transformation of this future’s value.

Examples:

future2 = future1.map { |value| value * 2 }

Parameters:

  • value (Object) (defaults to: nil)

    the value of this future (when no block is given)

Yield Parameters:

  • value (Object)

    the value of this future

Yield Returns:

  • (Object)

    the transformed value

Returns:

  • (Ione::Future)

    a new future representing the transformed value

Since:

  • v1.0.0


384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
# File 'lib/ione/future.rb', line 384

def map(value=nil, &block)
  f = CompletableFuture.new
  on_complete do |v, e|
    if e
      f.fail(e)
    else
      begin
        f.resolve(block ? block.call(v) : value)
      rescue => e
        f.fail(e)
      end
    end
  end
  f
end

#recover(value = nil) {|error| ... } ⇒ Ione::Future

Returns a new future which represents either the value of the original future, or the result of the given block, if the original future fails.

This method is similar to , but is triggered by a failure. You can also think of it as a rescue block for asynchronous operations.

If the block raises an error a failed future with that error will be returned (this can be used to transform an error into another error, instead of tranforming an error into a value).

Examples:

future2 = future1.recover { |error| 'foo' }
future1.fail(error)
future2.value # => 'foo'

Parameters:

  • value (Object) (defaults to: nil)

    the value when no block is given

Yield Parameters:

  • error (Object)

    the error from the original future

Yield Returns:

  • (Object)

    the value of the new future

Returns:

  • (Ione::Future)

    a new future representing a value recovered from the error

Since:

  • v1.0.0


504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
# File 'lib/ione/future.rb', line 504

def recover(value=nil, &block)
  f = CompletableFuture.new
  on_complete do |v, e|
    if e
      begin
        f.resolve(block ? block.call(e) : value)
      rescue => e
        f.fail(e)
      end
    else
      f.resolve(v)
    end
  end
  f
end

#then {|value| ... } ⇒ Ione::Future

Returns a new future representing a transformation of this future’s value, similarily to , but acts as when the block returns a Ione::Future.

This method is useful when you want to transform the value of a future, but whether or not it can be done synchronously or require an asynchronous operation depends on the value of the future.

Examples:

future1 = load_something
future2 = future1.then do |result|
  if result.empty?
    # make a new async call to load fallback value
    load_something_else
  else
    result
  end
end

Yield Parameters:

  • value (Object)

    the value of this future

Yield Returns:

  • (Object, Ione::Future)

    the transformed value, or a future that will resolve to the transformed value.

Returns:

  • (Ione::Future)

    a new future representing the transformed value

Since:

  • v1.2.0


458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
# File 'lib/ione/future.rb', line 458

def then(&block)
  f = CompletableFuture.new
  on_complete do |v, e|
    if e
      f.fail(e)
    else
      begin
        fv = block.call(v)
        if fv.respond_to?(:on_complete)
          fv.on_complete do |vv, ee|
            if ee
              f.fail(ee)
            else
              f.resolve(vv)
            end
          end
        else
          f.resolve(fv)
        end
      rescue => e
        f.fail(e)
      end
    end
  end
  f
end