The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Mojolicious-7.49
River stage four • 943 direct dependents • 1041 total dependents
496 ++
/ Mojo::IOLoop::Delay

NAME

Mojo::IOLoop::Delay - Promises/A+ and flow-control helpers

SYNOPSIS

  use Mojo::IOLoop::Delay;

  # Wrap continuation-passing style APIs with promises
  my $ua = Mojo::UserAgent->new;
  sub get {
    my $promise = Mojo::IOLoop->delay;
    $ua->get(@_ => sub {
      my ($ua, $tx) = @_;
      $promise->resolve($tx);
    });
    return $promise;
  }
  my $mojo = get('http://mojolicious.org');
  my $cpan = get('http://metacpan.org');
  $mojo->race($cpan)->then(sub { say shift->req->url })->wait;

  # Synchronize multiple non-blocking operations
  my $delay = Mojo::IOLoop::Delay->new;
  $delay->steps(sub { say 'BOOM!' });
  for my $i (1 .. 10) {
    my $end = $delay->begin;
    Mojo::IOLoop->timer($i => sub {
      say 10 - $i;
      $end->();
    });
  }
  $delay->wait;

  # Sequentialize multiple non-blocking operations
  Mojo::IOLoop::Delay->new->steps(

    # First step (simple timer)
    sub {
      my $delay = shift;
      Mojo::IOLoop->timer(2 => $delay->begin);
      say 'Second step in 2 seconds.';
    },

    # Second step (concurrent timers)
    sub {
      my ($delay, @args) = @_;
      Mojo::IOLoop->timer(1 => $delay->begin);
      Mojo::IOLoop->timer(3 => $delay->begin);
      say 'Third step in 3 seconds.';
    },

    # Third step (the end)
    sub {
      my ($delay, @args) = @_;
      say 'And done after 5 seconds total.';
    }
  )->wait;

DESCRIPTION

Mojo::IOLoop::Delay is a Perl-ish implementation of Promises/A+ and provides flow-control helpers for Mojo::IOLoop, which can help you avoid deep nested closures that often result from continuation-passing style.

  use Mojo::IOLoop;

  # These deep nested closures are often referred to as "Callback Hell"
  Mojo::IOLoop->timer(3 => sub {
    my loop = shift;

    say '3 seconds';
    Mojo::IOLoop->timer(3 => sub {
      my $loop = shift;

      say '6 seconds';
      Mojo::IOLoop->timer(3 => sub {
        my $loop = shift;

        say '9 seconds';
        Mojo::IOLoop->stop;
      });
    });
  });

  Mojo::IOLoop->start;

The idea behind Mojo::IOLoop::Delay is to turn the nested closures above into a flat series of closures. In the example below, the call to "begin" creates a code reference that we can pass to "timer" in Mojo::IOLoop as a callback, and that leads to the next closure in the series when executed.

  use Mojo::IOLoop;

  # Instead of nested closures we now have a simple chain
  my $delay = Mojo::IOloop->delay(
    sub {
      my $delay = shift;
      Mojo::IOLoop->timer(3 => $delay->begin);
    },
    sub {
      my $delay = shift;
      say '3 seconds';
      Mojo::IOLoop->timer(3 => $delay->begin);
    },
    sub {
      my $delay = shift;
      say '6 seconds';
      Mojo::IOLoop->timer(3 => $delay->begin);
    },
    sub {
      my $delay = shift;
      say '9 seconds';
    }
  );
  $delay->wait;

Another positive side effect of this pattern is that we do not need to call "start" in Mojo::IOLoop and "stop" in Mojo::IOLoop manually, because we know exactly when our series of closures has reached the end. So "wait" can stop the event loop automatically if it had to be started at all in the first place.

EVENTS

Mojo::IOLoop::Delay inherits all events from Mojo::EventEmitter and can emit the following new ones.

error

  $delay->on(error => sub {
    my ($delay, $err) = @_;
    ...
  });

Emitted if an exception gets thrown in one of the "steps", breaking the chain, fatal if unhandled.

finish

  $delay->on(finish => sub {
    my ($delay, @args) = @_;
    ...
  });

Emitted once the event counter reaches zero and there are no more "steps".

ATTRIBUTES

Mojo::IOLoop::Delay implements the following attributes.

ioloop

  my $loop = $delay->ioloop;
  $delay   = $delay->ioloop(Mojo::IOLoop->new);

Event loop object to control, defaults to the global Mojo::IOLoop singleton.

METHODS

Mojo::IOLoop::Delay inherits all methods from Mojo::EventEmitter and implements the following new ones.

all

  my $new = $delay->all(@delays);

Returns a new Mojo::IOLoop::Delay object that either fulfills when all of the passed Mojo::IOLoop::Delay objects have fulfilled or rejects as soon as one of them rejects. If the returned promise fulfills, it is fulfilled with the values from the fulfilled promises in the same order as the passed promises. This method can be useful for aggregating results of multiple promises.

begin

  my $cb = $delay->begin;
  my $cb = $delay->begin($offset);
  my $cb = $delay->begin($offset, $len);

Indicate an active event by incrementing the event counter, the returned code reference can be used as a callback, and needs to be executed when the event has completed to decrement the event counter again. When all code references generated by this method have been executed and the event counter has reached zero, "steps" will continue.

  # Capture all arguments except for the first one (invocant)
  my $delay = Mojo::IOLoop->delay(sub {
    my ($delay, $err, $stream) = @_;
    ...
  });
  Mojo::IOLoop->client({port => 3000} => $delay->begin);
  $delay->wait;

Arguments passed to the returned code reference are spliced with the given offset and length, defaulting to an offset of 1 with no default length. The arguments are then combined in the same order "begin" was called, and passed together to the next step or "finish" event.

  # Capture all arguments
  my $delay = Mojo::IOLoop->delay(sub {
    my ($delay, $loop, $err, $stream) = @_;
    ...
  });
  Mojo::IOLoop->client({port => 3000} => $delay->begin(0));
  $delay->wait;

  # Capture only the second argument
  my $delay = Mojo::IOLoop->delay(sub {
    my ($delay, $err) = @_;
    ...
  });
  Mojo::IOLoop->client({port => 3000} => $delay->begin(1, 1));
  $delay->wait;

  # Capture and combine arguments
  my $delay = Mojo::IOLoop->delay(sub {
    my ($delay, $three_err, $three_stream, $four_err, $four_stream) = @_;
    ...
  });
  Mojo::IOLoop->client({port => 3000} => $delay->begin);
  Mojo::IOLoop->client({port => 4000} => $delay->begin);
  $delay->wait;

catch

  my $new = $delay->catch(sub {...});

Appends a rejection handler callback to the promise, and returns a new Mojo::IOLoop::Delay object resolving to the return value of the callback if it is called, or to its original fulfillment value if the promise is instead fulfilled.

  # Longer version
  $delay->then(undef, sub {...});

  # Pass along the rejection reason
  $delay->catch(sub {
    my @reason = @_;
    warn "Something went wrong: $reason[0]";
    return @reason;
  });

  # Change the rejection reason
  $delay->catch(sub {
    my @reason = @_;
    return "This is bad: $reason[0]";
  });

finally

  my $new = $delay->finally(sub {...});

Appends a fulfillment and rejection handler to the promise, and returns a new Mojo::IOLoop::Delay object resolving to the original fulfillment value or rejection reason.

  # Do something on fulfillment and rejection
  $delay->finally(sub {
    my @value_or_reason = @_;
    say "We are done!";
  });

pass

  $delay = $delay->pass;
  $delay = $delay->pass(@args);

Shortcut for passing values between "steps".

  # Longer version
  $delay->begin(0)->(@args);

race

  my $new = $delay->race(@delays);

Returns a new Mojo::IOLoop::Delay object that fulfills or rejects as soon as one of the passed Mojo::IOLoop::Delay objects fulfills or rejects, with the value or reason from that promise.

reject

  $delay = $delay->reject(@reason);

Reject the promise with one or more rejection reasons.

resolve

  $delay = $delay->resolve(@value);

Resolve the promise with one or more fulfillment values.

steps

  $delay = $delay->steps(sub {...}, sub {...});

Sequentialize multiple events, every time the event counter reaches zero a callback will run, the first one automatically runs during the next reactor tick unless it is delayed by incrementing the event counter. This chain will continue until there are no remaining callbacks, a callback does not increment the event counter or an exception gets thrown in a callback. Finishing the chain will also result in the promise being fulfilled, or if an exception got thrown it will be rejected.

then

  my $new = $delay->then(sub {...});
  my $new = $delay->then(sub {...}, sub {...});
  my $new = $delay->then(undef, sub {...});

Appends fulfillment and rejection handlers to the promise, and returns a new Mojo::IOLoop::Delay object resolving to the return value of the called handler.

  # Pass along the fulfillment value or rejection reason
  $delay->then(sub {
    my @value = @_;
    say "The result is $value[0]";
    return @value;
  },
  sub {
    my @reason = @_;
    warn "Something went wrong: $reason[0]";
    return @reason;
  });

  # Change the fulfillment value or rejection reason
  $delay->then(sub {
    my @value = @_;
    return "This is good: $value[0]";
  },
  sub {
    my @reason = @_;
    return "This is bad: $reason[0]";
  });

wait

  $delay->wait;

Start "ioloop" and stop it again once the promise has been fulfilled or rejected, does nothing when "ioloop" is already running.

SEE ALSO

Mojolicious, Mojolicious::Guides, http://mojolicious.org.