use AnyEvent::Util;
All functions documented without "AnyEvent::Util::" prefix are exported by default.
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.
Returns the empty list on any errors.
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 AnyEvent::IO together with IO::AIO).
fork_call {
open my $fh, "</etc/passwd"
or die "passwd: $!";
local $/;
<$fh>
} sub {
my ($passwd) = @_;
...
};
The environment variable "PERL_ANYEVENT_MAX_FORKS" is used to initialise this value.
Instead of using this function, you could use "AnyEvent::fh_block" or "AnyEvent::fh_unblock".
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.
While the code is allowed to throw exceptions in unusual conditions, it is not defined whether this exception will be reported (at the moment, the Guard module and AnyEvent's pure-perl implementation both try to report the error and continue).
You can call one method on the returned object:
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;
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 first array element is used both for the executable name and argv[0]).
The key-value pairs can be:
Specifying the same scalar in multiple ``>'' pairs is allowed, e.g. to redirect both stdout and stderr into the same scalar:
">" => \$output,
"2>" => \$output,
The condvar will not be signalled before EOF or an error is signalled.
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.
Similarly, either the write data must be exhausted or an error is to be signalled before the condvar is signalled, for both string-reference and callback forms.
This can be useful to set up the environment in special ways, such as changing the priority of the command or manipulating signal handlers (e.g. setting "SIGINT" to "IGNORE").
See "close_all_fds_except" for more details.
Note the the PID might already have been recycled and used by an unrelated process at the time "run_cmd" returns, so it's not useful to send signals, use as a unique key in data structures and so on.
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";
});
Croaks when it cannot encode the string.
Croaks when it cannot decode the string.
If you have no clue what this means, look at "idn_to_ascii" instead.
This function is designed to avoid using a lot of resources - it uses about 1MB of RAM (most of this due to Unicode::Normalize). Also, names that are already ``simple'' will only be checked for basic validity, without the overhead of full nameprep processing.
Unlike some other ``ToAscii'' implementations, this one works on full domain names and should never fail - if it cannot convert the name, then it will return it unchanged.
This function is an amalgam of IDNA2003, UTS#46 and IDNA2008 - it tries to be reasonably compatible to other implementations, reasonably secure, as much as IDNs can be secure, and reasonably efficient when confronted with IDNs that are already valid DNS names.
Unlike some other ``ToUnicode'' implementations, this one works on full domain names and should never fail - if it cannot convert the name, then it will return it unchanged.
This function is an amalgam of IDNA2003, UTS#46 and IDNA2008 - it tries to be reasonably compatible to other implementations, reasonably secure, as much as IDNs can be secure, and reasonably efficient when confronted with IDNs that are already valid DNS names.
At the moment, this function simply calls "idn_nameprep $idn, 1", returning its argument when that function fails.
Marc Lehmann <schmorp@schmorp.de> http://anyevent.schmorp.de