File Coverage

blib/lib/Future/AsyncAwait/Hooks.pm

Criterion	Covered	Total	%
statement	19	20	95.0
branch	3	6	50.0
condition			n/a
subroutine	5	5	100.0
pod	0	1	0.0
total	27	32	84.3

#  You may distribute under the terms of either the GNU General Public License
#  or the Artistic License (the same terms as Perl itself)
#
#  (C) Paul Evans, 2023 -- [e-mail]

package Future::AsyncAwait::Hooks 0.02;

use v5.14;
use warnings;

use Carp;

require XSLoader;
XSLoader::load( __PACKAGE__, our $VERSION );

=head1 NAME

C - scoped hook blocks that run extra code around C expressions

=head1 SYNOPSIS

   use Future::AsyncAwait;
   use Future::AsyncAwait::Hooks;

   async sub do_work
   {
      suspend { say "do_work is pausing here" }
      resume  { say "do_Work has woken up again" }

      my $result = (await inner_1()) + (await inner_2());
      return $result;
   }

=head1 DESCRIPTION

This module provides two extra syntax keywords for inserting code that can
observe the suspend and resume behaviour of C expressions within an
C.

These two keywords are lexically scoped. They affect C expressions
later within their own scope, or scopes nested within it. They do not affect
any C expressions in scopes outside of those in which they appear.

=cut

=head1 KEYWORDS

=head2 suspend

   async sub {
      suspend { BLOCK }
   }

Inserts a block of code to run every time a subsequent C expression
at this block level pauses execution of the C.

=head2 resume

   async sub {
      resume { BLOCK }
   }

Inserts a block of code to run every time a subsequent C expression
at this block level resumes execution of the C after a pause.

=cut

sub import
{
   my $class = shift;
   my $caller = caller;

   $class->import_into( $caller, @_ );
}

sub import_into
{
   my $class = shift;
   my ( $caller, @syms ) = @_;

   @syms or @syms = qw( suspend resume );

   my %syms = map { $_ => 1 } @syms;

   foreach (qw( suspend resume )) {
      $^H{"Future::AsyncAwait::Hooks/$_"}++ if delete $syms{$_};
   }

   croak "Unrecognised import symbols @{[ keys %syms ]}" if keys %syms;
}

=head1 TODO

=over 4

=item *

Maybe work out why it doesn't appear to work on perls older than 5.24. Or
maybe nobody will be writing new code and needs it back that old?

=back

=cut

=head1 AUTHOR

Paul Evans

=cut

0x55AA;