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 windows, 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 on windows, so do not expect any speed from that, and using pipe everywhere else).

See portable_socketpair, below, for a bidirectional "pipe".

Returns the empty list on any errors.

($fh1, $fh2) = portable_socketpair

Just like portable_pipe, above, but returns a bidirectional pipe (usually by calling socketpair to create a local loopback socket pair, except on windows, where it again returns two interconnected TCP sockets).

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 undefined.

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.

The Guard module will be used to implement this function, if it is available. Otherwise a pure-perl implementation is used.

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.

AnyEvent::Util::close_all_fds_except @fds

This rarely-used function simply closes all file descriptors (or tries to) of the current process except the ones given as arguments.

When you want to start a long-running background server, then it is often beneficial to do this, as too many C-libraries are too stupid to mark their internal fd's as close-on-exec.

The function expects to be called shortly before an exec call.

Example: close all fds except 0, 1, 2.

   close_all_fds_except 0, 2, 1;

$cv = run_cmd $cmd, key => value...

Run a given external command, potentially redirecting file descriptors and return a condition variable that gets sent the exit status (like $?) when the program exits and all redirected file descriptors have been exhausted.

The $cmd is either a single string, which is then passed to a shell, or an arrayref, which is passed to the execvp function.

The key-value pairs can be:

">" => $filename

Redirects program standard output into the specified filename, similar to >filename in the shell.

">" => \$data

Appends program standard output to the referenced scalar. The condvar will not be signalled before EOF was received.

">" => $filehandle

Redirects program standard output to the given filehandle (or actualy its underlying file descriptor).

">" => $callback->($data)

Calls the given callback each time standard output receives some data, passing it the data received. On EOF, the callback will be invoked once without any arguments.

"fd>" => $see_above

Like ">", but redirects the specified fd number instead.

"<" => $see_above

The same, but redirects the program's standard input instead. The same forms as for ">" are allowed.

In the callback form, the callback is supposed to return data to be written, or the empty list or undef or a zero-length scalar to signal EOF.

"fd<" => $see_above

Like "<", but redirects the specified file descriptor instead.

on_prepare => $cb

Specify a callback that is executed just before the comamnd is exec'ed, in the child process. Be careful not to use any event handling or other services not available in the child.

This can be useful to set up the environment in special ways, such as changing the priority of the command.

close_all => $boolean

When close_all is enabled (default is disabled), then all extra file descriptors will be closed, except the ones that were redirected and 0, 1 and 2.

See close_all_fds_except for more details.

Example: run rm -rf /, redirecting standard input, output and error to /dev/null.

   my $cv = run_cmd [qw(rm -rf /)],
      "<", "/dev/null",
      ">", "/dev/null",
      "2>", "/dev/null";
   $cv->recv and die "d'oh! something survived!"

Example: run openssl and create a self-signed certificate and key, storing them in $cert and $key. When finished, check the exit status in the callback and print key and certificate.

   my $cv = run_cmd [qw(openssl req 
                     -new -nodes -x509 -days 3650
                     -newkey rsa:2048 -keyout /dev/fd/3
                     -batch -subj /CN=AnyEvent
                    )],
      "<", "dev/null",
      ">" , \my $cert,
      "3>", \my $key,
      "2>", "/dev/null";

   $cv->cb (sub {
      shift->recv and die "openssl failed";

      print "$key\n$cert\n";
   });

AUTHOR

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