Acme-Sort-Sleep

 view release on metacpan or  search on metacpan

local/lib/perl5/Future.pm  view on Meta::CPAN

    return $self;
 }

If an instance provides a method called C<await>, this will be called by the
C<get> and C<failure> methods if the instance is pending.

 $f->await

In most cases this should allow future-returning modules to be used as if they
were blocking call/return-style modules, by simply appending a C<get> call to
the function or method calls.

 my ( $results, $here ) = future_returning_function( @args )->get;

The F<examples> directory in the distribution contains some examples of how
futures might be integrated with various event systems.

=head2 DEBUGGING

By the time a C<Future> object is destroyed, it ought to have been completed

local/lib/perl5/Future.pm  view on Meta::CPAN

   my ( $op, $cb ) = @_;
   return $cb;
}

=head1 EXAMPLES

The following examples all demonstrate possible uses of a C<Future>
object to provide a fictional asynchronous API.

For more examples, comparing the use of C<Future> with regular call/return
style Perl code, see also L<Future::Phrasebook>.

=head2 Providing Results

By returning a new C<Future> object each time the asynchronous function is
called, it provides a placeholder for its eventual result, and a way to
indicate when it is complete.

 sub foperation
 {
    my %args = @_;

local/lib/perl5/Future.pm  view on Meta::CPAN

In particular, it is unclear in each of the following examples what the
behaviour of C<$f2> should be, were C<$f1> to be cancelled:

 $f2 = $f1->then( sub { ... } ); # plus related ->then_with_f, ...

 $f2 = $f1->else( sub { ... } ); # plus related ->else_with_f, ...

 $f2 = $f1->followed_by( sub { ... } );

In the C<then>-style case it is likely that this situation should be treated
as if C<$f1> had failed, perhaps with some special message. The C<else>-style
case is more complex, because it may be that the entire operation should still
fail, or it may be that the cancellation of C<$f1> should again be treated
simply as a special kind of failure, and the C<else> logic run as normal.

To be specific; in each case it is unclear what happens if the first future is
cancelled, while the second one is still waiting on it. The semantics for
"normal" top-down cancellation of C<$f2> and how it affects C<$f1> are already
clear and defined.

=head2 Cancellation of Divergent Flow

local/lib/perl5/Future/Phrasebook.pod  view on Meta::CPAN

#  (C) Paul Evans, 2013-2014 -- leonerd@leonerd.org.uk

=head1 NAME

C<Future::Phrasebook> - coding examples for C<Future> and C<Future::Utils>

This documentation-only module provides a phrasebook-like approach to giving
examples on how to use L<Future> and L<Future::Utils> to structure
Future-driven asynchronous or concurrent logic. As with any inter-dialect
phrasebook it is structured into pairs of examples; each given first in a
traditional call/return Perl style, and second in a style using Futures. In
each case, the generic function or functions in the example are named in
C<ALL_CAPITALS()> to make them stand out.

In the examples showing use of Futures, any function that is expected to
return a C<Future> instance is named with a leading C<F_> prefix. Each example
is also constructed so as to yield an overall future in a variable called
C<$f>, which represents the entire operation.

=head1 SEQUENCING

local/lib/perl5/Future/Phrasebook.pod  view on Meta::CPAN

       if( $result == $value ) {
          return F_ACTION();
       }
       else {
          return $f_cond;
       }
    });

=head1 EXCEPTION HANDLING

In regular call/return style code, if any function throws an exception, the
remainder of the block is not executed, the containing C<try> or C<eval> is
aborted, and control is passed to the corresponding C<catch> or line after the
C<eval>.

 try {
    FIRST();
 }
 catch {
    my $e = $_;
    ERROR( $e );

local/lib/perl5/Future/Phrasebook.pod  view on Meta::CPAN

Here, if C<$escape_f> is completed by the condition test, the future chain
returned by the code (that is, the C<then> chain of the C<repeat> block
followed by C<MAKE_NEW_ITEM()>) will be cancelled, and C<$f> itself will
receive this result.

=head1 CONCURRENCY

This final section of the phrasebook demonstrates a number of abilities that
are simple to do with C<Future> but can't easily be done with regular
call/return style programming, because they all involve an element of
concurrency. In these examples the comparison with regular call/return code
will be somewhat less accurate because of the inherent ability for the
C<Future>-using version to behave concurrently.

=head2 Waiting on Multiple Functions

The C<< Future->wait_all >> constructor creates a C<Future> that waits for all
of the component futures to complete. This can be used to form a sequence with
concurrency.

local/lib/perl5/IO/Async.pm  view on Meta::CPAN

L</SEE ALSO> section below for more detail.

As well as these general-purpose classes, the L<IO::Async::Loop> constructor
also supports looking for OS-specific subclasses, in case a more efficient
implementation exists for the specific OS it runs on.

=head2 Child Processes

The L<IO::Async::Loop> object provides a number of methods to facilitate the
running of child processes. C<spawn_child> is primarily a wrapper around the
typical C<fork(2)>/C<exec(2)> style of starting child processes, and
C<run_child> provide a method similar to perl's C<readpipe> (which is used
to implement backticks C<``>).

=head2 File Change Watches

The L<IO::Async::File> object observes changes to C<stat(2)> properties of a
file, directory, or other filesystem object. It invokes callbacks when
properties change. This is used by L<IO::Async::FileStream> which presents
the same events as a L<IO::Async::Stream> but operates on a regular file on
the filesystem, observing it for updates.

local/lib/perl5/IO/Async.pm  view on Meta::CPAN

represents an ongoing source of activity, such as a readable filehandle of
bytes or a POSIX signal.

Futures are a recent addition to the C<IO::Async> API and details are still
subject to change and experimentation.

In general, methods that support Futures return a new Future object to
represent the outstanding operation. If callback functions are supplied as
well, these will be fired in addition to the Future object becoming ready. Any
failures that are reported will, in general, use the same conventions for the
Future's C<fail> arguments to relate it to the legacy C<on_error>-style
callbacks.

 $on_NAME_error->( $message, @argmuents )

 $f->fail( $message, NAME, @arguments )

where C<$message> is a message intended for humans to read (so that this is
the message displayed by C<< $f->get >> if the failure is not otherwise
caught), C<NAME> is the name of the failing operation. If the failure is due
to a failed system call, the value of C<$!> will be the final argument. The

local/lib/perl5/IO/Async/Channel.pm  view on Meta::CPAN

A C<IO::Async::Channel> object allows Perl values to be passed into or out of
an L<IO::Async::Routine>. It is intended to be used primarily with a Routine
object rather than independently. For more detail and examples on how to use
this object see also the documentation for L<IO::Async::Routine>.

A Channel object is shared between the main process of the program and the
process running within the Routine. In the main process it will be used in
asynchronous mode, and in the Routine process it will be used in synchronous
mode. In asynchronous mode all methods return immediately and use
L<IO::Async>-style futures or callback functions. In synchronous within the
Routine process the methods block until they are ready and may be used for
flow-control within the routine. Alternatively, a Channel may be shared
between two different Routine objects, and not used directly by the
controlling program.

The channel itself represents a FIFO of Perl reference values. New values may
be put into the channel by the C<send> method in either mode. Values may be
retrieved from it by the C<recv> method. Values inserted into the Channel are
snapshot by the C<send> method. Any changes to referred variables will not be
observed by the other end of the Channel after the C<send> method returns.

local/lib/perl5/IO/Async/OS.pm  view on Meta::CPAN

# Can we rename() files that are open?
use constant HAVE_RENAME_OPEN_FILES => 1;

# Do we have IO::Socket::IP available?
use constant HAVE_IO_SOCKET_IP => defined eval { require IO::Socket::IP };

# Can we reliably watch for POSIX signals, including SIGCHLD to reliably
# inform us that a fork()ed child has exit()ed?
use constant HAVE_SIGNALS => 1;

# Do we support POSIX-style true fork()ed processes at all?
use constant HAVE_POSIX_FORK => !$ENV{IO_ASYNC_NO_FORK};
# Can we potentially support threads? (would still need to 'require threads')
use constant HAVE_THREADS => !$ENV{IO_ASYNC_NO_THREADS} &&
   eval { require Config && $Config::Config{useithreads} };

# Preferred trial order for built-in Loop classes
use constant LOOP_BUILTIN_CLASSES => qw( Poll Select );

# Should there be any other Loop classes we try before the builtin ones?
use constant LOOP_PREFER_CLASSES => ();

local/lib/perl5/IO/Async/Resolver.pm  view on Meta::CPAN

   die [ "$err", $err+0 ] if $err;

   return [ $host, $service ];
};

=head1 EXAMPLES

The following somewhat contrieved example shows how to implement a new
resolver function. This example just uses in-memory data, but a real function
would likely make calls to OS functions to provide an answer. In traditional
Unix style, a pair of functions are provided that each look up the entity by
either type of key, where both functions return the same type of list. This is
purely a convention, and is in no way required or enforced by the
L<IO::Async::Resolver> itself.

 @numbers = qw( zero  one   two   three four
                five  six   seven eight nine  );

 register_resolver getnumberbyindex => sub {
    my ( $index ) = @_;
    die "Bad index $index" unless $index >= 0 and $index < @numbers;

local/lib/perl5/Module/Build.pm  view on Meta::CPAN

argument whose value is a whitespace-separated list of test scripts to
run.  This is especially useful in development, when you only want to
run a single test to see whether you've squashed a certain bug yet:

  ./Build test --test_files t/something_failing.t

You may also pass several C<test_files> arguments separately:

  ./Build test --test_files t/one.t --test_files t/two.t

or use a C<glob()>-style pattern:

  ./Build test --test_files 't/01-*.t'

=item testall

[version 0.2807]

[Note: the 'testall' action and the code snippets below are currently
in alpha stage, see
L<"http://www.nntp.perl.org/group/perl.module.build/2007/03/msg584.html"> ]

local/lib/perl5/Module/Build.pm  view on Meta::CPAN

[version 0.05]

This is a synonym for the 'test' action with the C<debugger=1>
argument.

=item testpod

[version 0.25]

This checks all the files described in the C<docs> action and
produces C<Test::Harness>-style output.  If you are a module author,
this is useful to run before creating a new release.

=item testpodcoverage

[version 0.28]

This checks the pod coverage of the distribution and
produces C<Test::Harness>-style output. If you are a module author,
this is useful to run before creating a new release.

=item versioninstall

[version 0.16]

** Note: since C<only.pm> is so new, and since we just recently added
support for it here too, this feature is to be considered
experimental. **

local/lib/perl5/Module/Build.pm  view on Meta::CPAN

=head1 OPTIONS

=head2 Command Line Options

The following options can be used during any invocation of C<Build.PL>
or the Build script, during any action.  For information on other
options specific to an action, see the documentation for the
respective action.

NOTE: There is some preliminary support for options to use the more
familiar long option style.  Most options can be preceded with the
C<--> long option prefix, and the underscores changed to dashes
(e.g. C<--use-rcfile>).  Additionally, the argument to boolean options is
optional, and boolean options can be negated by prefixing them with
C<no> or C<no-> (e.g. C<--noverbose> or C<--no-verbose>).

=over 4

=item quiet

Suppress informative messages on output.

local/lib/perl5/Module/Build/API.pod  view on Meta::CPAN

C<Software::License> on the author's machine, and further requires
that the C<license> parameter specifies a license that it knows about.

=item create_makefile_pl

[version 0.19]

This parameter lets you use C<Module::Build::Compat> during the
C<distdir> (or C<dist>) action to automatically create a Makefile.PL
for compatibility with C<ExtUtils::MakeMaker>.  The parameter's value
should be one of the styles named in the L<Module::Build::Compat>
documentation.

=item create_readme

[version 0.22]

This parameter tells Module::Build to automatically create a F<README>
file at the top level of your distribution.  Currently it will simply
use C<Pod::Text> (or C<Pod::Readme> if it's installed) on the file
indicated by C<dist_version_from> and put the result in the F<README>
file.  This is by no means the only recommended style for writing a
F<README>, but it seems to be one common one used on the CPAN.

If you generate a F<README> in this way, it's probably a good idea to
create a separate F<INSTALL> file if that information isn't in the
generated F<README>.

=item dist_abstract

[version 0.20]

local/lib/perl5/Module/Build/API.pod  view on Meta::CPAN

file(s) they generate as hash values, like so:

  my $build = Module::Build->new
    (
     module_name => 'Foo::Bar',
     ...
     PL_files => { 'lib/Foo/Bar.pm.PL' => 'lib/Foo/Bar.pm' },
    );

Note that the path specifications are I<always> given in Unix-like
format, not in the style of the local system.

If your C<.PL> scripts don't create any files, or if they create files
with unexpected names, or even if they create multiple files, you can
indicate that so that Module::Build can properly handle these created
files:

  PL_files => {
               'lib/Foo/Bar.pm.PL' => 'lib/Foo/Bar.pm',
               'lib/something.PL'  => ['/lib/something', '/lib/else'],
               'lib/funny.PL'      => [],

local/lib/perl5/Module/Build/API.pod  view on Meta::CPAN

=item pm_files

[version 0.19]

An optional parameter specifying the set of C<.pm> files in this
distribution, specified as a hash reference whose keys are the files'
locations in the distributions, and whose values are their logical
locations based on their package name, i.e. where they would be found
in a "normal" Module::Build-style distribution.  This parameter is
mainly intended to support alternative layouts of files.

For instance, if you have an old-style C<MakeMaker> distribution for a
module called C<Foo::Bar> and a F<Bar.pm> file at the top level of the
distribution, you could specify your layout in your C<Build.PL> like
this:

  my $build = Module::Build->new
    (
     module_name => 'Foo::Bar',
     ...
     pm_files => { 'Bar.pm' => 'lib/Foo/Bar.pm' },
    );

Note that the values should include C<lib/>, because this is where
they would be found in a "normal" Module::Build-style distribution.

Note also that the path specifications are I<always> given in
Unix-like format, not in the style of the local system.

=item pod_files

[version 0.19]

Just like C<pm_files>, but used for specifying the set of C<.pod>
files in your distribution.

=item recommends

local/lib/perl5/Module/Build/API.pod  view on Meta::CPAN

L<TAP::Harness|TAP::Harness> documentation for details. Note that specifying
this parameter will implicitly set C<use_tap_harness> to a true value. You
must therefore be sure to add TAP::Harness as a requirement for your module in
L</build_requires>.

=item test_files

[version 0.23]

An optional parameter specifying a set of files that should be used as
C<Test::Harness>-style regression tests to be run during the C<test>
action.  May be given as an array reference of the files, or as a hash
reference whose keys are the files (and whose values will currently be
ignored).  If the argument is given as a single string (not in an
array reference), that string will be treated as a C<glob()> pattern
specifying the files to use.

The default is to look for a F<test.pl> script in the top-level
directory of the distribution, and any files matching the glob pattern
C<*.t> in the F<t/> subdirectory.  If the C<recursive_test_files>
property is true, then the C<t/> directory will be scanned recursively

local/lib/perl5/Module/Build/Base.pm  view on Meta::CPAN

}


# install paths must be generated when requested to be sure all changes
# to config (from various sources) are included
sub _default_install_paths {
  my $self = shift;
  my $c = $self->{config};
  my $p = {};

  my @libstyle = $c->get('installstyle') ?
      File::Spec->splitdir($c->get('installstyle')) : qw(lib perl5);
  my $arch     = $c->get('archname');
  my $version  = $c->get('version');

  my $bindoc  = $c->get('installman1dir') || undef;
  my $libdoc  = $c->get('installman3dir') || undef;

  my $binhtml = $c->get('installhtml1dir') || $c->get('installhtmldir') || undef;
  my $libhtml = $c->get('installhtml3dir') || $c->get('installhtmldir') || undef;

  $p->{install_sets} =

local/lib/perl5/Module/Build/Base.pm  view on Meta::CPAN

  $p->{original_prefix} =
    {
     core   => $c->get('installprefixexp') || $c->get('installprefix') ||
               $c->get('prefixexp')        || $c->get('prefix') || '',
     site   => $c->get('siteprefixexp'),
     vendor => $c->get('usevendorprefix') ? $c->get('vendorprefixexp') : '',
    };
  $p->{original_prefix}{site} ||= $p->{original_prefix}{core};

  # Note: you might be tempted to use $Config{installstyle} here
  # instead of hard-coding lib/perl5, but that's been considered and
  # (at least for now) rejected.  `perldoc Config` has some wisdom
  # about it.
  $p->{install_base_relpaths} =
    {
     lib     => ['lib', 'perl5'],
     arch    => ['lib', 'perl5', $arch],
     bin     => ['bin'],
     script  => ['bin'],
     bindoc  => ['man', 'man1'],
     libdoc  => ['man', 'man3'],
     binhtml => ['html'],
     libhtml => ['html'],
    };

  $p->{prefix_relpaths} =
    {
     core => {
       lib        => [@libstyle],
       arch       => [@libstyle, $version, $arch],
       bin        => ['bin'],
       script     => ['bin'],
       bindoc     => ['man', 'man1'],
       libdoc     => ['man', 'man3'],
       binhtml    => ['html'],
       libhtml    => ['html'],
     },
     vendor => {
       lib        => [@libstyle],
       arch       => [@libstyle, $version, $arch],
       bin        => ['bin'],
       script     => ['bin'],
       bindoc     => ['man', 'man1'],
       libdoc     => ['man', 'man3'],
       binhtml    => ['html'],
       libhtml    => ['html'],
     },
     site => {
       lib        => [@libstyle, 'site_perl'],
       arch       => [@libstyle, 'site_perl', $version, $arch],
       bin        => ['bin'],
       script     => ['bin'],
       bindoc     => ['man', 'man1'],
       libdoc     => ['man', 'man3'],
       binhtml    => ['html'],
       libhtml    => ['html'],
     },
    };
    return $p
}

local/lib/perl5/Module/Build/Base.pm  view on Meta::CPAN

    $files_found++;

    # Code below modified from /usr/bin/perldoc

    # Skip to ACTIONS section
    local $_;
    while (<$fh>) {
      last if /^=head1 ACTIONS\s/;
    }

    # Look for our action and determine the style
    my $style;
    while (<$fh>) {
      last if /^=head1 /;

      # only item and head2 are allowed (3&4 are not in 5.005)
      if(/^=(item|head2)\s+\Q$action\E\b/) {
        $style = $1;
        push @docs, $_;
        last;
      }
    }
    $style or next; # not here

    # and the content
    if($style eq 'item') {
      my ($found, $inlist) = (0, 0);
      while (<$fh>) {
        if (/^=(item|back)/) {
          last unless $inlist;
        }
        push @docs, $_;
        ++$inlist if /^=over/;
        --$inlist if /^=back/;
      }
    }
    else { # head2 style
      # stop at anything equal or greater than the found level
      while (<$fh>) {
        last if(/^=(?:head[12]|cut)/);
        push @docs, $_;
      }
    }
    # TODO maybe disallow overriding just pod for an action
    # TODO and possibly: @docs and last;
  }

local/lib/perl5/Module/Build/Base.pm  view on Meta::CPAN

    local $Test::Harness::verbose = $self->verbose || 0;
    local $Test::Harness::switches = join ' ', $self->harness_switches;

    Test::Harness::runtests(@$tests);
}

sub run_visual_script {
    my $self = shift;
    # This will get run and the user will see the output.  It doesn't
    # emit Test::Harness-style output.
    $self->run_perl_script('visual.pl', '-Mblib='.$self->blib)
        if -e 'visual.pl';
}

sub harness_switches {
    my $self = shift;
    my @res;
    push @res, qw(-w -d) if $self->{properties}{debugger};
    push @res, '-MDevel::Cover' if $self->{properties}{cover};
    return @res;

local/lib/perl5/Module/Build/Compat.pm  view on Meta::CPAN

sub create_makefile_pl {
  my ($package, $type, $build, %args) = @_;

  die "Don't know how to build Makefile.PL of type '$type'"
    unless $type =~ /^(small|passthrough|traditional)$/;

  if ($type eq 'passthrough') {
    $build->log_warn(<<"HERE");

IMPORTANT NOTE: The '$type' style of Makefile.PL is deprecated and
may be removed in a future version of Module::Build in favor of the
'configure_requires' property.  See Module::Build::Compat
documentation for details.

HERE
  }

  my $fh;
  if ($args{fh}) {
    $fh = $args{fh};

local/lib/perl5/Module/Build/Compat.pm  view on Meta::CPAN

  ...


=head1 DESCRIPTION

Because C<ExtUtils::MakeMaker> has been the standard way to distribute
modules for a long time, many tools (CPAN.pm, or your system
administrator) may expect to find a working F<Makefile.PL> in every
distribution they download from CPAN.  If you want to throw them a
bone, you can use C<Module::Build::Compat> to automatically generate a
F<Makefile.PL> for you, in one of several different styles.

C<Module::Build::Compat> also provides some code that helps out the
F<Makefile.PL> at runtime.


=head1 METHODS

=over 4

=item create_makefile_pl($style, $build)

Creates a F<Makefile.PL> in the current directory in one of several
styles, based on the supplied C<Module::Build> object C<$build>.  This is
typically controlled by passing the desired style as the
C<create_makefile_pl> parameter to C<Module::Build>'s C<new()> method;
the F<Makefile.PL> will then be automatically created during the
C<distdir> action.

The currently supported styles are:

=over 4

=item traditional

A F<Makefile.PL> will be created in the "traditional" style, i.e. it will
use C<ExtUtils::MakeMaker> and won't rely on C<Module::Build> at all.
In order to create the F<Makefile.PL>, we'll include the C<requires> and
C<build_requires> dependencies as the C<PREREQ_PM> parameter.

You don't want to use this style if during the C<perl Build.PL> stage
you ask the user questions, or do some auto-sensing about the user's
environment, or if you subclass C<Module::Build> to do some
customization, because the vanilla F<Makefile.PL> won't do any of that.

=item small

A small F<Makefile.PL> will be created that passes all functionality
through to the F<Build.PL> script in the same directory.  The user must
already have C<Module::Build> installed in order to use this, or else
they'll get a module-not-found error.

local/lib/perl5/Module/Build/Compat.pm  view on Meta::CPAN

the build.

This option has been deprecated and may be removed in a future version
of Module::Build.  Modern CPAN.pm and CPANPLUS will recognize the
C<configure_requires> metadata property and install Module::Build before
running Build.PL if Module::Build is listed and Module::Build now
adds itself to configure_requires by default.

Perl 5.10.1 includes C<configure_requires> support.  In the future, when
C<configure_requires> support is deemed sufficiently widespread, the
C<passthrough> style will be removed.

=back

=item run_build_pl(args => \@ARGV)

This method runs the F<Build.PL> script, passing it any arguments the
user may have supplied to the C<perl Makefile.PL> command.  Because
C<ExtUtils::MakeMaker> and C<Module::Build> accept different arguments, this
method also performs some translation between the two.

local/lib/perl5/Module/Build/Cookbook.pm  view on Meta::CPAN

=head2 Making a CPAN.pm-compatible distribution

New versions of CPAN.pm understand how to use a F<Build.PL> script,
but old versions don't.  If authors want to help users who have old
versions, some form of F<Makefile.PL> should be supplied.  The easiest
way to accomplish this is to use the C<create_makefile_pl> parameter to
C<< Module::Build->new() >> in the C<Build.PL> script, which can
create various flavors of F<Makefile.PL> during the C<dist> action.

As a best practice, we recommend using the "traditional" style of
F<Makefile.PL> unless your distribution has needs that can't be
accomplished that way.

The C<Module::Build::Compat> module, which is part of
C<Module::Build>'s distribution, is responsible for creating these
F<Makefile.PL>s.  Please see L<Module::Build::Compat> for the details.


=head2 Changing the order of the build process