NAME

Venus::Future - Future Class

ABSTRACT

Future Class for Perl 5

SYNOPSIS

  package main;

  use Venus::Future;

  my $future = Venus::Future->new;

  # bless({...}, 'Venus::Future')

  # $future->promise(sub{
  #   my ($resolve, $reject) = @_;
  #   $resolve->result(1);
  # });

  # bless({...}, 'Venus::Future')

  # $future->fulfill;

  # true

DESCRIPTION

This package provides a framework-agnostic "Future" and implementation of the "Promise/A+" pattern for asynchronous programming. The futures are non-blocking and support "suspend" and "resume" allowing them to be used in any asynchronous operating environment.

INHERITS

This package inherits behaviors from:

Venus::Kind::Utility

INTEGRATES

This package integrates behaviors from:

Venus::Role::Buildable

METHODS

This package provides the following methods:

catch

  catch(coderef $on_reject) (Venus::Future)

The catch method registers a rejection handler and returns the future that invokes the handlers.

Since 3.55

catch example 1

  # given: synopsis

  package main;

  my $catch = $future->catch(sub{
    my ($issue) = @_;

    return $issue;
  });

  # bless(..., "Venus::Future")

  # $catch->then(sub{...});

  # bless(..., "Venus::Future")

catch example 2

  # given: synopsis

  package main;

  my $catch = $future->catch(sub{
    my ($issue) = @_;

    return $issue;
  });

  # bless(..., "Venus::Future")

  $future = $future;

  # bless(..., "Venus::Future")

  # $future->reject('Oops!');

  # bless(..., "Venus::Future")

finally

  finally(coderef $on_finally) (Venus::Future)

The finally method registers a finally handler and returns the future that invokes the handlers.

Since 3.55

finally example 1

  # given: synopsis

  package main;

  my $finally = $future->finally(sub{
    my ($data) = @_;

    return $data;
  });

  # bless(..., "Venus::Future")

  # $finally->then(sub{...});

  # bless(..., "Venus::Future")

finally example 2

  # given: synopsis

  package main;

  $future->then(sub{
    $_
  });

  my $finally = $future->finally(sub{
    my ($data) = @_;

    $future->{stash} = $data;

    return $data;
  });

  # bless(..., "Venus::Future")

  $future = $future;

  # bless(..., "Venus::Future")

  # $future->resolve('Hello.');

  # bless(..., "Venus::Future")

finally example 3

  # given: synopsis

  package main;

  $future->then(sub{
    $_
  });

  my $finally = $future->finally(sub{
    my ($data) = @_;

    $future->{stash} = $data;

    return $data;
  });

  # bless(..., "Venus::Future")

  $future = $future;

  # bless(..., "Venus::Future")

  # $future->reject('Oops!');

  # bless(..., "Venus::Future")

fulfill

  fulfill() (Venus::Future)

The fulfill method attempts to fulfill the promise by actuating it, or resuming a previously actuated promise, and returns true if the future has been resolved, i.e. the future is either is_fulfilled or is_rejected, and otherwise returns false.

Since 3.55

fulfill example 1

  # given: synopsis

  package main;

  $future->promise(sub{
    # resolve
    $_[0]->result;
  });

  my $fulfilled = $future->fulfill;

  # true

fulfill example 2

  # given: synopsis

  package main;

  $future->promise(sub{
    # resolve
    $_[0]->result;
  });

  $future->fulfill;

  my $result = $future;

  # bless(..., "Venus::Future")

  # $result->is_fulfilled;

  # true

  # $result->value;

  # undef

fulfill example 3

  # given: synopsis

  package main;

  $future->promise(sub{
    # resolve
    $_[1]->result;
  });

  my $fulfilled = $future->fulfill;

  # true

fulfill example 4

  # given: synopsis

  package main;

  $future->promise(sub{
    # resolve
    $_[1]->result;
  });

  $future->fulfill;

  my $result = $future;

  # bless(..., "Venus::Future")

  # $result->is_rejected;

  # true

  # $result->issue;

  # undef

fulfill example 5

  # given: synopsis

  package main;

  $future->promise(sub{
    # resolve
    $_[0]->result(1);
  })->then(sub{
    return $future->{stash} = $_ * 2; # 2
  })->then(sub{
    return $future->{stash} = $_ * 2; # 4
  })->then(sub{
    return $future->{stash} = $_ * 2; # 8
  });

  $future->fulfill;

  my $result = $future;

  # bless(..., "Venus::Future")

  # $result->is_fulfilled;

  # true

  # $result->value;

  # 1

fulfill example 6

  # given: synopsis

  package main;

  $future->promise(sub{
    # resolve
    $_[0]->result(1);
  });

  $future->then(sub{
    return $future->{stash} = $_ * 2; # 2
  });

  $future->then(sub{
    return $future->{stash} = $_ * 2; # 2
  });

  $future->then(sub{
    return $future->{stash} = $_ * 2; # 2
  });

  $future->fulfill;

  my $result = $future;

  # bless(..., "Venus::Future")

  # $result->is_fulfilled;

  # true

  # $result->value;

  # 1

fulfill example 7

  # given: synopsis

  package main;

  my $pending_future = Venus::Future->new;

  $future->promise(sub{
    # resolve
    $_[0]->result(1);
  })->then(sub{
    return $_
  })->then(sub{
    return $pending_future;
  })->then(sub{
    return $_
  });

  $future->fulfill;

  my @results = ($future, $pending_future);

  # my $result = $future;

  # bless(..., "Venus::Future")

  # $result->is_fulfilled;

  # false

  # $result->is_pending;

  # true

  # $result->value;

  # undef

  # $pending_future->resolve(0);

  # bless(..., "Venus::Future")

  # $pending_future->is_fulfilled;

  # true

  # $result->fulfill;

  # true

  # $result->is_fulfilled;

  # true

fulfill example 8

  # given: synopsis

  package Thenable;

  use Venus::Class;

  sub then {
    my ($self, $resolve, $reject) = @_;

    $resolve->(100);
  }

  package main;

  my $thenable_object = Thenable->new;

  $future->promise(sub{
    # resolve
    $_[0]->result(1);
  })->then(sub{
    return $_
  })->then(sub{
    return $thenable_object;
  })->then(sub{
    return $future->{stash} = $_
  });

  $future->fulfill;

  my @results = ($future, $thenable_object);

  # my $result = $future;

  # bless(..., "Venus::Future")

  # $result->is_fulfilled;

  # true

  # $result->value;

  # 1

is

  is(string $name) (boolean)

The is method take a name and dispatches to the corresponding is_$name method and returns the result.

Since 3.55

is example 1

  # given: synopsis

  package main;

  $future->resolve;

  my $is_fulfilled = $future->is('fulfilled');

  # true

is example 2

  # given: synopsis

  package main;

  my $is_pending = $future->is('pending');

  # true

is example 3

  # given: synopsis

  package main;

  $future->reject;

  my $is_rejected = $future->is('rejected');

  # true

is_fulfilled

  is_fulfilled() (boolean)

The is_fulfilled method returns true if the future has been fulfilled, otherwise returns false.

Since 3.55

is_fulfilled example 1

  # given: synopsis

  package main;

  my $is_fulfilled = $future->is_fulfilled;

  # false

is_fulfilled example 2

  # given: synopsis

  package main;

  $future->resolve;

  my $is_fulfilled = $future->is_fulfilled;

  # true

is_fulfilled example 3

  # given: synopsis

  package main;

  $future->reject;

  my $is_fulfilled = $future->is_fulfilled;

  # false

is_pending

  is_pending() (boolean)

The is_pending method returns true if the future has remained pending, otherwise returns false.

Since 3.55

is_pending example 1

  # given: synopsis

  package main;

  my $is_pending = $future->is_pending;

  # true

is_pending example 2

  # given: synopsis

  package main;

  $future->resolve;

  my $is_pending = $future->is_pending;

  # false

is_pending example 3

  # given: synopsis

  package main;

  $future->reject;

  my $is_pending = $future->is_pending;

  # false

is_promised

  is_promised() (boolean)

The is_promised method returns true if the future a registered promise, otherwise returns false.

Since 3.55

is_promised example 1

  # given: synopsis

  package main;

  my $is_promised = $future->is_promised;

  # false

is_promised example 2

  # given: synopsis

  package main;

  $future->promise;

  my $is_promised = $future->is_promised;

  # false

is_promised example 3

  # given: synopsis

  package main;

  $future->promise(sub{$_[0]->result});

  my $is_promised = $future->is_promised;

  # true

is_rejected

  is_rejected() (boolean)

The is_rejected method returns true if the future has been rejected, otherwise returns false.

Since 3.55

is_rejected example 1

  # given: synopsis

  package main;

  my $is_rejected = $future->is_rejected;

  # false

is_rejected example 2

  # given: synopsis

  package main;

  $future->resolve;

  my $is_rejected = $future->is_rejected;

  # false

is_rejected example 3

  # given: synopsis

  package main;

  $future->reject;

  my $is_rejected = $future->is_rejected;

  # true

issue

  issue() (any)

The issue method returns the result of the "reject" operation once the future has been rejected.

Since 3.55

issue example 1

  # given: synopsis

  package main;

  my $issue = $future->issue;

  # undef

  # $future->is_pending

  # true

issue example 2

  # given: synopsis

  package main;

  $future->reject(0);

  my $issue = $future->issue;

  # 0

  # $future->is_rejected

  # true

issue example 3

  # given: synopsis

  package main;

  $future->reject({fail => 1});

  my $issue = $future->issue;

  # {fail => 1}

  # $future->is_rejected

  # true

new

  new(any @args) (Venus::Future)

The new method instantiates this package and returns a new instance.

Since 3.55

new example 1

  package main;

  my $future = Venus::Future->new;

  # bless(..., "Venus::Future")

new example 2

  package main;

  my $future = Venus::Future->new(sub{
    my ($resolve, $reject) = @_;
    $resolve->result('okay');
  });

  # bless(..., "Venus::Future")

  # $future->is('fulfilled');

  # true

  # $future->value;

  # 'okay'

new example 3

  package main;

  my $future = Venus::Future->new(promise => sub{
    my ($resolve, $reject) = @_;
    $reject->result('boom');
  });

  # bless(..., "Venus::Future")

  # $future->is('rejected');

  # true

  # $future->issue;

  # 'boom'

promise

  promise(coderef $code) (Venus::Future)

The promise method registers a callback executed by the "fulfill" method, which is provided two arguments; the first argument being a Venus::Try instance representing a resolve operaiton; the second argument being a Venus::Try instance representing a reject operaiton; and returns the invocant.

Since 3.55

promise example 1

  # given: synopsis

  package main;

  $future = $future->promise(sub{
    my ($resolve, $reject) = @_;

    $resolve->result('pass');
  });

  # bless(..., "Venus::Future")

  # $future->fulfill;

  # true

promise example 2

  # given: synopsis

  package main;

  $future = $future->promise(sub{
    my ($resolve, $reject) = @_;

    $reject->result('fail');
  });

  # bless(..., "Venus::Future")

  # $future->fulfill;

  # true

reject

  reject(any $issue) (Venus::Future)

The reject method cascades a rejection operation causes the future to be rejected, and returns the invocant.

Since 3.55

reject example 1

  # given: synopsis

  package main;

  my $rejected = $future->reject;

  # bless(..., "Venus::Future")

  # $rejected->status

  # "rejected"

  # $rejected->issue

  # undef

reject example 2

  # given: synopsis

  package main;

  my $rejected = $future->reject('Oops!');

  # bless(..., "Venus::Future")

  # $rejected->status

  # "rejected"

  # $rejected->issue

  # "Oops!"

resolve

  resolve(any $value) (Venus::Future)

The resolve method cascades a rejection operation causes the future to be rejected, and returns the invocant.

Since 3.55

resolve example 1

  # given: synopsis

  package main;

  my $fulfilled = $future->resolve;

  # bless(..., "Venus::Future")

  # $fulfilled->status

  # "fulfilled"

  # $fulfilled->value

  # undef

resolve example 2

  # given: synopsis

  package main;

  my $fulfilled = $future->resolve('Great!');

  # bless(..., "Venus::Future")

  # $fulfilled->status

  # "fulfilled"

  # $fulfilled->value

  # "Great!"

status

  status() (any)

The status method returns the status of the future. Valid statuses are fulfilled, pending, and rejected.

Since 3.55

status example 1

  # given: synopsis

  package main;

  my $status = $future->status;

  # "pending"

status example 2

  # given: synopsis

  package main;

  $future->resolve(0);

  my $status = $future->status;

  # "fulfilled"

status example 3

  # given: synopsis

  package main;

  $future->reject(0);

  my $status = $future->status;

  # "rejected"

then

  then(coderef $fulfill, coderef $reject) (Venus::Future)

The then method registers fulfillment and rejection handlers and returns the future that invokes the handlers.

Since 3.55

then example 1

  # given: synopsis

  package main;

  my $new_future = $future->then(sub{
    # fulfillment handler
    $_
  });

  # "Venus::Future"

  # $new_future->is_pending;

  # true

then example 2

  # given: synopsis

  package main;

  my $new_future = $future->then(sub{
    # fulfillment handler
    $_
  },
  sub{
    # rejection handler
    $_
  });

  # "Venus::Future"

  # $new_future->is_pending;

  # true

then example 3

  # given: synopsis

  package main;

  my $new_future = $future->then(undef, sub{
    # rejection handler
    $_
  });

  # "Venus::Future"

  # $new_future->is_pending;

  # true

then example 4

  # given: synopsis

  package main;

  my $new_future = $future->then(sub{
    # fulfillment handler
    $_
  });

  # "Venus::Future"

  # $new_future->is_pending;

  # true

  $future = $future;

  # "Venus::Future"

  # $new_future->is_pending;

  # true

then example 5

  # given: synopsis

  package main;

  my $new_future = $future->then(sub{
    # fulfillment handler
    $_
  },
  sub{
    # rejection handler
    $_
  });

  # "Venus::Future"

  # $new_future->is_pending;

  # true

  $future = $future;

  # "Venus::Future"

  # $new_future->is_pending;

  # true

then example 6

  # given: synopsis

  package main;

  my $new_future = $future->then(undef, sub{
    # rejection handler
    $_
  });

  # "Venus::Future"

  # $new_future->is_pending;

  # true

  $future = $future;

  # "Venus::Future"

  # $new_future->is_pending;

  # true

value

  value() (any)

The value method returns the result of the "resolve" operation once the future has been fulfilled.

Since 3.55

value example 1

  # given: synopsis

  package main;

  my $value = $future->value;

  # undef

  # $future->is_pending

  # true

value example 2

  # given: synopsis

  package main;

  $future->resolve(1);

  my $value = $future->value;

  # 1

  # $future->is_fulfilled

  # true

value example 3

  # given: synopsis

  package main;

  $future->resolve({pass => 1});

  my $value = $future->value;

  # {pass => 1}

  # $future->is_fulfilled

  # true

wait

  wait(number $timeout) (Venus::Future)

The wait method blocks the execution of the current process until a value is received. If a timeout is provided, execution will be blocked until a value is received or the wait time expires. If a timeout of 0 is provided, execution will not be blocked. If no timeout is provided at all, execution will block indefinitely.

Since 3.55

wait example 1

  # given: synopsis

  package main;

  $future->promise(sub{
    # resolve
    $_[0]->result;
  });

  $future = $future->wait(0);

  # bless(..., "Venus::Future")

  # $future->is_fulfilled;

  # true

wait example 2

  # given: synopsis

  package main;

  $future->promise(sub{
    # never fulfilled
  });

  $future->wait(1);

  # Exception! (isa Venus::Future::Error) (see error_on_timeout)

ERRORS

This package may raise the following errors:

error: error_on_timeout

This package may raise an error_on_timeout exception.

example 1

  # given: synopsis;

  my $input = {
    throw => 'error_on_timeout',
    timeout => 10,
  };

  my $error = $future->try('error', $input)->error->result;

  # my $name = $error->name;

  # "on_timeout"

  # my $message = $error->render;

  # "Future timed-out after 10 seconds"

  # my $timeout = $error->stash('timeout');

  # 10

AUTHORS

Awncorp, awncorp@cpan.org

LICENSE

This program is free software, you can redistribute it and/or modify it under the terms of the Apache license version 2.0.

To install Venus, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Venus

CPAN shell

perl -MCPAN -e shell
install Venus

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

ABSTRACT

SYNOPSIS

DESCRIPTION

INHERITS

INTEGRATES

METHODS

catch

finally

fulfill

is

is_fulfilled

is_pending

is_promised

is_rejected

issue

new

promise

reject

resolve

status

then

value

wait

ERRORS

AUTHORS

LICENSE

Module Install Instructions