• NAME
• SYNOPSIS
• DESCRIPTION
• ATTRIBUTES
• METHODS
• begin
• pass
• steps
• SEE ALSO

NAME

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

SYNOPSIS

  use Mojo::IOLoop::Delay;

  # 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

the Mojo::IOLoop::Delay manpage adds flow-control helpers to the Mojo::Promise manpage, 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 the Mojo::IOLoop::Delay manpage 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 the Mojo::IOLoop manpage 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 of steps
  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 the Mojo::IOLoop manpage and stop in the Mojo::IOLoop manpage manually, because we know exactly when our chain of steps has reached the end. So wait in the Mojo::Promise manpage can stop the event loop automatically if it had to be started at all in the first place.

ATTRIBUTES

the Mojo::IOLoop::Delay manpage inherits all attributes from the Mojo::Promise manpage.

METHODS

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

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.

  # 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;

pass

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

Shortcut for passing values between steps.

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

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.

SEE ALSO

Mojolicious, the Mojolicious::Guides manpage, https://mojolicious.org.