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