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

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

ATTRIBUTES

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

METHODS

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

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

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

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

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

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

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

SEE ALSO

Mojolicious, Mojolicious::Guides, <https://mojolicious.org>.