view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

# NAME

Async::Template - Async Template Toolkit

# SYNOPSIS

    use Async::Template (tt);

    my $cv = AnyEvent->condvar;

    my $tt = Async::Template->new({
       # ... any Template options (see Template::Manual::Config)
       INCLUDE_PATH => $src,
       ENCODING => 'utf8',

       # additional options provided by Async::Template

       # optional blocker if only one blocking tt instance is required
       # default AnyEvent blocker is enabled if no DONE handler is provided
       BLOCKER => sub{ $cv->recv; },

       # done handler - called when template process is finished
       # default event loop and blocker is enabled if DONE is not specified
       # may be redefined at the process() function
       DONE => sub{ my $output = shift; $cv->send; },
    }) || die Async::Template->error();


    # single blocked process

    my $tt = Async::Template->new({}) || die Async::Template->error();
    $tt->process($template, $vars, \$output)


    # nonblocked multiple procesess

    my $cv = AnyEvent->condvar;
    $cv->begin;
    my $tt2 = Async::Template->new({
       DONE => sub{ my $output = shift; $cv->end; },
    }) || die Async::Template->error();
    $cv->begin;
    AnyEvent->timer(after => 10, cb => sub { $cv->end; });
    $cv->recv


    # usage in perl code for async processes

    my $vars = {
      some_async_fn => sub {
         my ($param, $callback) = @_;
         $callback->(error, result);
      },
      api => SomeObj->new({}),
    }

    tt $vars, << 'END',
       USE timeout = Second;
       AWAIT timeout.start(10)

       r = AWAIT api.call('endpoint', {param = 'val'});
       error = ERROR(r);
       result = RESULT(r);
       RETURN IF ERROR(r);

       p2 = ASYNC some_async_fn('param');
       p1 = ASYNC api.call('endpoint', {});
       AWAIT p1;
       AWAIT p2;
       RETURN IF RESULT(r);
     END
     sub{
        use Data::Dumper; warn Dumper \@_;
        die $_[0] if($_[0]);
        print 'result: ', $_[1];
     };

# DESCRIPTION

Async::Template is the same as Template Toolkit with asynchronous interface and
with asynchronous operators ASYNC/AWAIT which can be used with any event
management system (like [AnyEvent](https://metacpan.org/pod/AnyEvent)).

To refer Template Toolkit language syntax, configure options, params and other
documentation folow this link [Template](https://metacpan.org/pod/Template).

Operators like ASYNC/AWAIT itself is not an function or something wich applied
locally at the place where it is used in the code. Such operators affect all
the code generation and the execution sequences. Any block of code cease to be
a block if at least one async operator is exists in it. Loops, blocks,
conditions, switches, and so on become different in synchronous and asynchronous
implementations.

For example a synchronous loop is continuous sequence which at the end of loop
has a transition to the begin of the loop. But the asynchronous loop is not
a continuos sequence and to do transition to the begin of loop typical loop
operators can not be used because begin and end of loop located in different
unjoined betwen each other code sequences (in a different fuctions).
This is because at the middle of the loop at the place of async operator
presents a finish of the execution and return. This return must be supported
by each of parent block statement. Execution must be returned to the very top
of the execution - to the event loop. And after awaited event condition is
reached the execution must continue from that place from which it was returned.