AnyEvent::Util(3p)

NAME
AnyEvent::Util - various utility functions.

SYNOPSIS
   use AnyEvent::Util;

DESCRIPTION
This module implements various utility functions, mostly replacing well-known functions by event-ised counterparts.

All functions documented without "AnyEvent::Util::" prefix are exported by default.

($r, $w) = portable_pipe
    Calling "pipe" in Perl is portable - except it doesn't really work on sucky windows platforms (at least not with most perls - cygwin's perl notably works fine).

    On that platform, you actually get two file handles you cannot use select on.

    This function gives you a pipe that actually works even on the broken Windows platform (by creating a pair of TCP sockets, so do not expect any speed from that).

    Returns the empty list on any errors.

fork_call { CODE } @args, $cb->(@res)
    Executes the given code block asynchronously, by forking. Everything the block returns will be transferred to the calling process (by serialising and deserialising via Storable).

    If there are any errors, then the $cb will be called without any arguments. In that case, either $@ contains the exception (and $! is irrelevant), or $! contains an error number. In all other cases, $@ will be "undef"ined.

    The code block must not ever call an event-polling function or use event-based programming that might cause any callbacks registered in the parent to run.

    Win32 spoilers: Due to the endlessly sucky and broken native windows perls (there is no way to cleanly exit a child process on that platform that doesn't also kill the parent), you have to make sure that your main program doesn't exit as long as any "fork_calls" are still in progress, otherwise the program won't exit. Also, on most windows platforms some memory will leak for every invocation. We are open for improvements that don't require XS hackery.

    Note that forking can be expensive in large programs (RSS 200MB+). On windows, it is abysmally slow, do not expect more than 5..20 forks/s on that sucky platform (note this uses perl's pseudo-threads, so avoid those like the plague).

    Example: poor man's async disk I/O (better use IO::AIO).

       fork_call {
          open my $fh, "</etc/passwd"
             or die "passwd: $!";
          local $/;
          <$fh>
       } sub {
          my ($passwd) = @_;
          ...
       };

$AnyEvent::Util::MAX_FORKS [default: 10]
    The maximum number of child processes that "fork_call" will fork in parallel. Any additional requests will be queued until a slot becomes free again.

    The environment variable "PERL_ANYEVENT_MAX_FORKS" is used to initialise this value.

fh_nonblocking $fh, $nonblocking
    Sets the blocking state of the given filehandle (true == nonblocking, false == blocking). Uses fcntl on anything sensible and ioctl FIONBIO on broken (i.e. windows) platforms.

$guard = guard { CODE }
    This function creates a special object that, when called, will execute the code block.

    This is often handy in continuation-passing style code to clean up some resource regardless of where you break out of a process.

    You can call one method on the returned object:

$guard->cancel
    This simply causes the code block not to be invoked: it "cancels" the guard.

AUTHOR
 Marc Lehmann <schmorp@schmorp.de>
 http://home.schmorp.de/