1AnyEvent::Util(3) User Contributed Perl Documentation AnyEvent::Util(3)
2
6 AnyEvent::Util - various utility functions.
7
9 use AnyEvent::Util;
10
12 This module implements various utility functions, mostly replacing
13 well-known functions by event-ised counterparts.
14 All functions documented without "AnyEvent::Util::" prefix are exported
16 by default.
17 ($r, $w) = portable_pipe
19 Calling "pipe" in Perl is portable - except it doesn't really work
20 on sucky windows platforms (at least not with most perls - cygwin's
21 perl notably works fine): On windows, you actually get two file
22 handles you cannot use select on.
23 This function gives you a pipe that actually works even on the
25 broken windows platform (by creating a pair of TCP sockets on
26 windows, so do not expect any speed from that, and using "pipe"
27 everywhere else).
28 See "portable_socketpair", below, for a bidirectional "pipe".
30 Returns the empty list on any errors.
32 ($fh1, $fh2) = portable_socketpair
34 Just like "portable_pipe", above, but returns a bidirectional pipe
35 (usually by calling "socketpair" to create a local loopback socket
36 pair, except on windows, where it again returns two interconnected
37 TCP sockets).
38 Returns the empty list on any errors.
40 fork_call { CODE } @args, $cb->(@res)
42 Executes the given code block asynchronously, by forking.
43 Everything the block returns will be transferred to the calling
44 process (by serialising and deserialising via Storable).
45 If there are any errors, then the $cb will be called without any
47 arguments. In that case, either $@ contains the exception (and $!
48 is irrelevant), or $! contains an error number. In all other cases,
49 $@ will be "undef"ined.
50 The code block must not ever call an event-polling function or use
52 event-based programming that might cause any callbacks registered
53 in the parent to run.
54 Win32 spoilers: Due to the endlessly sucky and broken native
56 windows perls (there is no way to cleanly exit a child process on
57 that platform that doesn't also kill the parent), you have to make
58 sure that your main program doesn't exit as long as any
59 "fork_calls" are still in progress, otherwise the program won't
60 exit. Also, on most windows platforms some memory will leak for
61 every invocation. We are open for improvements that don't require
62 XS hackery.
63 Note that forking can be expensive in large programs (RSS 200MB+).
65 On windows, it is abysmally slow, do not expect more than 5..20
66 forks/s on that sucky platform (note this uses perl's pseudo-
67 threads, so avoid those like the plague).
68 Example: poor man's async disk I/O (better use IO::AIO).
70 fork_call {
72 open my $fh, "</etc/passwd"
73 or die "passwd: $!";
74 local $/;
75 <$fh>
76 } sub {
77 my ($passwd) = @_;
78 ...
79 };
80 $AnyEvent::Util::MAX_FORKS [default: 10]
82 The maximum number of child processes that "fork_call" will fork in
83 parallel. Any additional requests will be queued until a slot
84 becomes free again.
85 The environment variable "PERL_ANYEVENT_MAX_FORKS" is used to
87 initialise this value.
88 fh_nonblocking $fh, $nonblocking
90 Sets the blocking state of the given filehandle (true ==
91 nonblocking, false == blocking). Uses fcntl on anything sensible
92 and ioctl FIONBIO on broken (i.e. windows) platforms.
93 $guard = guard { CODE }
95 This function creates a special object that, when called, will
96 execute the code block.
97 This is often handy in continuation-passing style code to clean up
99 some resource regardless of where you break out of a process.
100 The Guard module will be used to implement this function, if it is
102 available. Otherwise a pure-perl implementation is used.
103 You can call one method on the returned object:
105 $guard->cancel
107 This simply causes the code block not to be invoked: it "cancels"
108 the guard.
109 AnyEvent::Util::close_all_fds_except @fds
111 This rarely-used function simply closes all file descriptors (or
112 tries to) of the current process except the ones given as
113 arguments.
114 When you want to start a long-running background server, then it is
116 often beneficial to do this, as too many C-libraries are too stupid
117 to mark their internal fd's as close-on-exec.
118 The function expects to be called shortly before an "exec" call.
120 Example: close all fds except 0, 1, 2.
122 close_all_fds_except 0, 2, 1;
124 $cv = run_cmd $cmd, key => value...
126 Run a given external command, potentially redirecting file
127 descriptors and return a condition variable that gets sent the exit
128 status (like $?) when the program exits and all redirected file
129 descriptors have been exhausted.
130 The $cmd is either a single string, which is then passed to a
132 shell, or an arrayref, which is passed to the "execvp" function.
133 The key-value pairs can be:
135 ">" => $filename
137 Redirects program standard output into the specified filename,
138 similar to ">filename" in the shell.
139 ">" => \$data
141 Appends program standard output to the referenced scalar. The
142 condvar will not be signalled before EOF or an error is
143 signalled.
144 ">" => $filehandle
146 Redirects program standard output to the given filehandle (or
147 actually its underlying file descriptor).
148 ">" => $callback->($data)
150 Calls the given callback each time standard output receives
151 some data, passing it the data received. On EOF or error, the
152 callback will be invoked once without any arguments.
153 The condvar will not be signalled before EOF or an error is
155 signalled.
156 "fd>" => $see_above
158 Like ">", but redirects the specified fd number instead.
159 "<" => $see_above
161 The same, but redirects the program's standard input instead.
162 The same forms as for ">" are allowed.
163 In the callback form, the callback is supposed to return data
165 to be written, or the empty list or "undef" or a zero-length
166 scalar to signal EOF.
167 Similarly, either the write data must be exhausted or an error
169 is to be signalled before the condvar is signalled, for both
170 string-reference and callback forms.
171 "fd<" => $see_above
173 Like "<", but redirects the specified file descriptor instead.
174 on_prepare => $cb
176 Specify a callback that is executed just before the comamnd is
177 "exec"'ed, in the child process. Be careful not to use any
178 event handling or other services not available in the child.
179 This can be useful to set up the environment in special ways,
181 such as changing the priority of the command.
182 close_all => $boolean
184 When "close_all" is enabled (default is disabled), then all
185 extra file descriptors will be closed, except the ones that
186 were redirected and 0, 1 and 2.
187 See "close_all_fds_except" for more details.
189 '$$' => \$pid
191 A reference to a scalar which will receive the PID of the
192 newly-created subprocess after "run_cmd" returns.
193 Note the the PID might already have been recycled and used by
195 an unrelated process at the time "run_cmd" returns, so it's not
196 useful to send signals, use a unique key in data structures and
197 so on.
198 Example: run "rm -rf /", redirecting standard input, output and
200 error to /dev/null.
201 my $cv = run_cmd [qw(rm -rf /)],
203 "<", "/dev/null",
204 ">", "/dev/null",
205 "2>", "/dev/null";
206 $cv->recv and die "d'oh! something survived!"
207 Example: run openssl and create a self-signed certificate and key,
209 storing them in $cert and $key. When finished, check the exit
210 status in the callback and print key and certificate.
211 my $cv = run_cmd [qw(openssl req
213 -new -nodes -x509 -days 3650
214 -newkey rsa:2048 -keyout /dev/fd/3
215 -batch -subj /CN=AnyEvent
216 )],
217 "<", "dev/null",
218 ">" , \my $cert,
219 "3>", \my $key,
220 "2>", "/dev/null";
221 $cv->cb (sub {
223 shift->recv and die "openssl failed";
224 print "$key\n$cert\n";
226 });
227 AnyEvent::Util::punycode_encode $string
229 Punycode-encodes the given $string and returns its punycode form.
230 Note that uppercase letters are not casefolded - you have to do
231 that yourself.
232 Croaks when it cannot encode the string.
234 AnyEvent::Util::punycode_decode $string
236 Tries to punycode-decode the given $string and return it's unicode
237 form. Again, uppercase letters are not casefoled, you have to do
238 that yourself.
239 Croaks when it cannot decode the string.
241 AnyEvent::Util::idn_nameprep $idn[, $display]
243 Implements the IDNA nameprep normalisation algorithm. Or actually
244 the UTS#46 algorithm. Or maybe something similar - reality is
245 complicated btween IDNA2003, UTS#46 and IDNA2008. If $display is
246 true then the name is prepared for display, otherwise it is
247 prepared for lookup (default).
248 If you have no clue what this means, look at "idn_to_ascii"
250 instead.
251 This function is designed to avoid using a lot of resources - it
253 uses about 1MB of RAM (most of this due to Unicode::Normalize).
254 Also, names that are already "simple" will only be checked for
255 basic validity, without the overhead of full nameprep processing.
256 $domainname = AnyEvent::Util::idn_to_ascii $idn
258 Converts the given unicode string ($idn, international domain name,
259 e.g. aeXXaeXXeXXa~XXieXXieXX) to a pure-ASCII domain name (this is
260 usually called the "IDN ToAscii" transform). This transformation is
261 idempotent, which means you can call it just in case and it will do
262 the right thing.
263 Unlike some other "ToAscii" implementations, this one works on full
265 domain names and should never fail - if it cannot convert the name,
266 then it will return it unchanged.
267 This function is an amalgam of IDNA2003, UTS#46 and IDNA2008 - it
269 tries to be reasonably compatible to other implementations,
270 reasonably secure, as much as IDNs can be secure, and reasonably
271 efficient when confronted with IDNs that are already valid DNS
272 names.
273 $idn = AnyEvent::Util::idn_to_unicode $idn
275 Converts the given unicode string ($idn, international domain name,
276 e.g. aeXXaeXXeXXa~XXieXXieXX, www.deliantra.net, www.xn--l-0ga.de)
277 to unicode form (this is usually called the "IDN ToUnicode"
278 transform). This transformation is idempotent, which means you can
279 call it just in case and it will do the right thing.
280 Unlike some other "ToUnicode" implementations, this one works on
282 full domain names and should never fail - if it cannot convert the
283 name, then it will return it unchanged.
284 This function is an amalgam of IDNA2003, UTS#46 and IDNA2008 - it
286 tries to be reasonably compatible to other implementations,
287 reasonably secure, as much as IDNs can be secure, and reasonably
288 efficient when confronted with IDNs that are already valid DNS
289 names.
290 At the moment, this function simply calls "idn_nameprep $idn, 1",
292 returning it's argument when that function fails.
293
295 Marc Lehmann <schmorp@schmorp.de>
296 http://home.schmorp.de/
297perl v5.12.1 2010-02-23 AnyEvent::Util(3)