1AnyEvent::Handle(3) User Contributed Perl Documentation AnyEvent::Handle(3)
2
6 AnyEvent::Handle - non-blocking I/O on streaming handles via AnyEvent
7
9 use AnyEvent;
10 use AnyEvent::Handle;
11 my $cv = AnyEvent->condvar;
13 my $hdl; $hdl = new AnyEvent::Handle
15 fh => \*STDIN,
16 on_error => sub {
17 my ($hdl, $fatal, $msg) = @_;
18 AE::log error => $msg;
19 $hdl->destroy;
20 $cv->send;
21 };
22 # send some request line
24 $hdl->push_write ("getinfo\015\012");
25 # read the response line
27 $hdl->push_read (line => sub {
28 my ($hdl, $line) = @_;
29 say "got line <$line>";
30 $cv->send;
31 });
32 $cv->recv;
34
36 This is a helper module to make it easier to do event-based I/O on
37 stream-based filehandles (sockets, pipes, and other stream things).
38 Specifically, it doesn't work as expected on files, packet-based
39 sockets or similar things.
40 The AnyEvent::Intro tutorial contains some well-documented
42 AnyEvent::Handle examples.
43 In the following, where the documentation refers to "bytes", it means
45 characters. As sysread and syswrite are used for all I/O, their
46 treatment of characters applies to this module as well.
47 At the very minimum, you should specify "fh" or "connect", and the
49 "on_error" callback.
50 All callbacks will be invoked with the handle object as their first
52 argument.
53
55 $handle = new AnyEvent::Handle fh => $filehandle, key => value...
56 The constructor supports these arguments (all as "key => value"
57 pairs).
58 fh => $filehandle ["fh" or "connect" MANDATORY]
60 The filehandle this AnyEvent::Handle object will operate on.
61 NOTE: The filehandle will be set to non-blocking mode (using
62 "AnyEvent::fh_unblock") by the constructor and needs to stay in
63 that mode.
64 connect => [$host, $service] ["fh" or "connect" MANDATORY]
66 Try to connect to the specified host and service (port), using
67 "AnyEvent::Socket::tcp_connect". The $host additionally becomes
68 the default "peername".
69 You have to specify either this parameter, or "fh", above.
71 It is possible to push requests on the read and write queues,
73 and modify properties of the stream, even while
74 AnyEvent::Handle is connecting.
75 When this parameter is specified, then the "on_prepare",
77 "on_connect_error" and "on_connect" callbacks will be called
78 under the appropriate circumstances:
79 on_prepare => $cb->($handle)
81 This (rarely used) callback is called before a new
82 connection is attempted, but after the file handle has been
83 created (you can access that file handle via
84 "$handle->{fh}"). It could be used to prepare the file
85 handle with parameters required for the actual connect (as
86 opposed to settings that can be changed when the connection
87 is already established).
88 The return value of this callback should be the connect
90 timeout value in seconds (or 0, or "undef", or the empty
91 list, to indicate that the default timeout is to be used).
92 on_connect => $cb->($handle, $host, $port, $retry->())
94 This callback is called when a connection has been
95 successfully established.
96 The peer's numeric host and port (the socket peername) are
98 passed as parameters, together with a retry callback. At
99 the time it is called the read and write queues, EOF
100 status, TLS status and similar properties of the handle
101 will have been reset.
102 If, for some reason, the handle is not acceptable, calling
104 $retry will continue with the next connection target (in
105 case of multi-homed hosts or SRV records there can be
106 multiple connection endpoints). The $retry callback can be
107 invoked after the connect callback returns, i.e. one can
108 start a handshake and then decide to retry with the next
109 host if the handshake fails.
110 In most cases, you should ignore the $retry parameter.
112 on_connect_error => $cb->($handle, $message)
114 This callback is called when the connection could not be
115 established. $! will contain the relevant error code, and
116 $message a message describing it (usually the same as
117 "$!").
118 If this callback isn't specified, then "on_error" will be
120 called with a fatal error instead.
121 on_error => $cb->($handle, $fatal, $message)
123 This is the error callback, which is called when, well, some
124 error occured, such as not being able to resolve the hostname,
125 failure to connect, or a read error.
126 Some errors are fatal (which is indicated by $fatal being
128 true). On fatal errors the handle object will be destroyed (by
129 a call to "-> destroy") after invoking the error callback
130 (which means you are free to examine the handle object).
131 Examples of fatal errors are an EOF condition with active (but
132 unsatisfiable) read watchers ("EPIPE") or I/O errors. In cases
133 where the other side can close the connection at will, it is
134 often easiest to not report "EPIPE" errors in this callback.
135 AnyEvent::Handle tries to find an appropriate error code for
137 you to check against, but in some cases (TLS errors), this does
138 not work well.
139 If you report the error to the user, it is recommended to
141 always output the $message argument in human-readable error
142 messages (you don't need to report "$!" if you report
143 $message).
144 If you want to react programmatically to the error, then
146 looking at $! and comparing it against some of the documented
147 "Errno" values is usually better than looking at the $message.
148 Non-fatal errors can be retried by returning, but it is
150 recommended to simply ignore this parameter and instead abondon
151 the handle object when this callback is invoked. Examples of
152 non-fatal errors are timeouts "ETIMEDOUT") or badly-formatted
153 data ("EBADMSG").
154 On entry to the callback, the value of $! contains the
156 operating system error code (or "ENOSPC", "EPIPE", "ETIMEDOUT",
157 "EBADMSG" or "EPROTO").
158 While not mandatory, it is highly recommended to set this
160 callback, as you will not be notified of errors otherwise. The
161 default just calls "croak".
162 on_read => $cb->($handle)
164 This sets the default read callback, which is called when data
165 arrives and no read request is in the queue (unlike read queue
166 callbacks, this callback will only be called when at least one
167 octet of data is in the read buffer).
168 To access (and remove data from) the read buffer, use the
170 "->rbuf" method or access the "$handle->{rbuf}" member
171 directly. Note that you must not enlarge or modify the read
172 buffer, you can only remove data at the beginning from it.
173 You can also call "->push_read (...)" or any other function
175 that modifies the read queue. Or do both. Or ...
176 When an EOF condition is detected, AnyEvent::Handle will first
178 try to feed all the remaining data to the queued callbacks and
179 "on_read" before calling the "on_eof" callback. If no progress
180 can be made, then a fatal error will be raised (with $! set to
181 "EPIPE").
182 Note that, unlike requests in the read queue, an "on_read"
184 callback doesn't mean you require some data: if there is an EOF
185 and there are outstanding read requests then an error will be
186 flagged. With an "on_read" callback, the "on_eof" callback will
187 be invoked.
188 on_eof => $cb->($handle)
190 Set the callback to be called when an end-of-file condition is
191 detected, i.e. in the case of a socket, when the other side has
192 closed the connection cleanly, and there are no outstanding
193 read requests in the queue (if there are read requests, then an
194 EOF counts as an unexpected connection close and will be
195 flagged as an error).
196 For sockets, this just means that the other side has stopped
198 sending data, you can still try to write data, and, in fact,
199 one can return from the EOF callback and continue writing data,
200 as only the read part has been shut down.
201 If an EOF condition has been detected but no "on_eof" callback
203 has been set, then a fatal error will be raised with $! set to
204 <0>.
205 on_drain => $cb->($handle)
207 This sets the callback that is called once when the write
208 buffer becomes empty (and immediately when the handle object is
209 created).
210 To append to the write buffer, use the "->push_write" method.
212 This callback is useful when you don't want to put all of your
214 write data into the queue at once, for example, when you want
215 to write the contents of some file to the socket you might not
216 want to read the whole file into memory and push it into the
217 queue, but instead only read more data from the file when the
218 write queue becomes empty.
219 timeout => $fractional_seconds
221 rtimeout => $fractional_seconds
222 wtimeout => $fractional_seconds
223 If non-zero, then these enables an "inactivity" timeout:
224 whenever this many seconds pass without a successful read or
225 write on the underlying file handle (or a call to
226 "timeout_reset"), the "on_timeout" callback will be invoked
227 (and if that one is missing, a non-fatal "ETIMEDOUT" error will
228 be raised).
229 There are three variants of the timeouts that work
231 independently of each other, for both read and write (triggered
232 when nothing was read OR written), just read (triggered when
233 nothing was read), and just write: "timeout", "rtimeout" and
234 "wtimeout", with corresponding callbacks "on_timeout",
235 "on_rtimeout" and "on_wtimeout", and reset functions
236 "timeout_reset", "rtimeout_reset", and "wtimeout_reset".
237 Note that timeout processing is active even when you do not
239 have any outstanding read or write requests: If you plan to
240 keep the connection idle then you should disable the timeout
241 temporarily or ignore the timeout in the corresponding
242 "on_timeout" callback, in which case AnyEvent::Handle will
243 simply restart the timeout.
244 Zero (the default) disables the corresponding timeout.
246 on_timeout => $cb->($handle)
248 on_rtimeout => $cb->($handle)
249 on_wtimeout => $cb->($handle)
250 Called whenever the inactivity timeout passes. If you return
251 from this callback, then the timeout will be reset as if some
252 activity had happened, so this condition is not fatal in any
253 way.
254 rbuf_max => <bytes>
256 If defined, then a fatal error will be raised (with $! set to
257 "ENOSPC") when the read buffer ever (strictly) exceeds this
258 size. This is useful to avoid some forms of denial-of-service
259 attacks.
260 For example, a server accepting connections from untrusted
262 sources should be configured to accept only so-and-so much data
263 that it cannot act on (for example, when expecting a line, an
264 attacker could send an unlimited amount of data without a
265 callback ever being called as long as the line isn't finished).
266 wbuf_max => <bytes>
268 If defined, then a fatal error will be raised (with $! set to
269 "ENOSPC") when the write buffer ever (strictly) exceeds this
270 size. This is useful to avoid some forms of denial-of-service
271 attacks.
272 Although the units of this parameter is bytes, this is the raw
274 number of bytes not yet accepted by the kernel. This can make a
275 difference when you e.g. use TLS, as TLS typically makes your
276 write data larger (but it can also make it smaller due to
277 compression).
278 As an example of when this limit is useful, take a chat server
280 that sends chat messages to a client. If the client does not
281 read those in a timely manner then the send buffer in the
282 server would grow unbounded.
283 autocork => <boolean>
285 When disabled (the default), "push_write" will try to
286 immediately write the data to the handle if possible. This
287 avoids having to register a write watcher and wait for the next
288 event loop iteration, but can be inefficient if you write
289 multiple small chunks (on the wire, this disadvantage is
290 usually avoided by your kernel's nagle algorithm, see
291 "no_delay", but this option can save costly syscalls).
292 When enabled, writes will always be queued till the next event
294 loop iteration. This is efficient when you do many small writes
295 per iteration, but less efficient when you do a single write
296 only per iteration (or when the write buffer often is full). It
297 also increases write latency.
298 no_delay => <boolean>
300 When doing small writes on sockets, your operating system
301 kernel might wait a bit for more data before actually sending
302 it out. This is called the Nagle algorithm, and usually it is
303 beneficial.
304 In some situations you want as low a delay as possible, which
306 can be accomplishd by setting this option to a true value.
307 The default is your operating system's default behaviour (most
309 likely enabled). This option explicitly enables or disables it,
310 if possible.
311 keepalive => <boolean>
313 Enables (default disable) the SO_KEEPALIVE option on the stream
314 socket: normally, TCP connections have no time-out once
315 established, so TCP connections, once established, can stay
316 alive forever even when the other side has long gone. TCP
317 keepalives are a cheap way to take down long-lived TCP
318 connections when the other side becomes unreachable. While the
319 default is OS-dependent, TCP keepalives usually kick in after
320 around two hours, and, if the other side doesn't reply, take
321 down the TCP connection some 10 to 15 minutes later.
322 It is harmless to specify this option for file handles that do
324 not support keepalives, and enabling it on connections that are
325 potentially long-lived is usually a good idea.
326 oobinline => <boolean>
328 BSD majorly fucked up the implementation of TCP urgent data.
329 The result is that almost no OS implements TCP according to the
330 specs, and every OS implements it slightly differently.
331 If you want to handle TCP urgent data, then setting this flag
333 (the default is enabled) gives you the most portable way of
334 getting urgent data, by putting it into the stream.
335 Since BSD emulation of OOB data on top of TCP's urgent data can
337 have security implications, AnyEvent::Handle sets this flag
338 automatically unless explicitly specified. Note that setting
339 this flag after establishing a connection may be a bit too late
340 (data loss could already have occured on BSD systems), but at
341 least it will protect you from most attacks.
342 read_size => <bytes>
344 The initial read block size, the number of bytes this module
345 will try to read during each loop iteration. Each handle object
346 will consume at least this amount of memory for the read buffer
347 as well, so when handling many connections watch out for memory
348 requirements). See also "max_read_size". Default: 2048.
349 max_read_size => <bytes>
351 The maximum read buffer size used by the dynamic adjustment
352 algorithm: Each time AnyEvent::Handle can read "read_size"
353 bytes in one go it will double "read_size" up to the maximum
354 given by this option. Default: 131072 or "read_size", whichever
355 is higher.
356 low_water_mark => <bytes>
358 Sets the number of bytes (default: 0) that make up an "empty"
359 write buffer: If the buffer reaches this size or gets even
360 samller it is considered empty.
361 Sometimes it can be beneficial (for performance reasons) to add
363 data to the write buffer before it is fully drained, but this
364 is a rare case, as the operating system kernel usually buffers
365 data as well, so the default is good in almost all cases.
366 linger => <seconds>
368 If this is non-zero (default: 3600), the destructor of the
369 AnyEvent::Handle object will check whether there is still
370 outstanding write data and will install a watcher that will
371 write this data to the socket. No errors will be reported (this
372 mostly matches how the operating system treats outstanding data
373 at socket close time).
374 This will not work for partial TLS data that could not be
376 encoded yet. This data will be lost. Calling the "stoptls"
377 method in time might help.
378 peername => $string
380 A string used to identify the remote site - usually the DNS
381 hostname (not IDN!) used to create the connection, rarely the
382 IP address.
383 Apart from being useful in error messages, this string is also
385 used in TLS peername verification (see "verify_peername" in
386 AnyEvent::TLS). This verification will be skipped when
387 "peername" is not specified or is "undef".
388 tls => "accept" | "connect" | Net::SSLeay::SSL object
390 When this parameter is given, it enables TLS (SSL) mode, that
391 means AnyEvent will start a TLS handshake as soon as the
392 connection has been established and will transparently
393 encrypt/decrypt data afterwards.
394 All TLS protocol errors will be signalled as "EPROTO", with an
396 appropriate error message.
397 TLS mode requires Net::SSLeay to be installed (it will be
399 loaded automatically when you try to create a TLS handle): this
400 module doesn't have a dependency on that module, so if your
401 module requires it, you have to add the dependency yourself. If
402 Net::SSLeay cannot be loaded or is too old, you get an "EPROTO"
403 error.
404 Unlike TCP, TLS has a server and client side: for the TLS
406 server side, use "accept", and for the TLS client side of a
407 connection, use "connect" mode.
408 You can also provide your own TLS connection object, but you
410 have to make sure that you call either
411 "Net::SSLeay::set_connect_state" or
412 "Net::SSLeay::set_accept_state" on it before you pass it to
413 AnyEvent::Handle. Also, this module will take ownership of this
414 connection object.
415 At some future point, AnyEvent::Handle might switch to another
417 TLS implementation, then the option to use your own session
418 object will go away.
419 IMPORTANT: since Net::SSLeay "objects" are really only
421 integers, passing in the wrong integer will lead to certain
422 crash. This most often happens when one uses a stylish "tls =>
423 1" and is surprised about the segmentation fault.
424 Use the "->starttls" method if you need to start TLS
426 negotiation later.
427 tls_ctx => $anyevent_tls
429 Use the given "AnyEvent::TLS" object to create the new TLS
430 connection (unless a connection object was specified directly).
431 If this parameter is missing (or "undef"), then
432 AnyEvent::Handle will use "AnyEvent::Handle::TLS_CTX".
433 Instead of an object, you can also specify a hash reference
435 with "key => value" pairs. Those will be passed to
436 AnyEvent::TLS to create a new TLS context object.
437 on_starttls => $cb->($handle, $success[, $error_message])
439 This callback will be invoked when the TLS/SSL handshake has
440 finished. If $success is true, then the TLS handshake
441 succeeded, otherwise it failed ("on_stoptls" will not be called
442 in this case).
443 The session in "$handle->{tls}" can still be examined in this
445 callback, even when the handshake was not successful.
446 TLS handshake failures will not cause "on_error" to be invoked
448 when this callback is in effect, instead, the error message
449 will be passed to "on_starttls".
450 Without this callback, handshake failures lead to "on_error"
452 being called as usual.
453 Note that you cannot just call "starttls" again in this
455 callback. If you need to do that, start an zero-second timer
456 instead whose callback can then call "->starttls" again.
457 on_stoptls => $cb->($handle)
459 When a SSLv3/TLS shutdown/close notify/EOF is detected and this
460 callback is set, then it will be invoked after freeing the TLS
461 session. If it is not, then a TLS shutdown condition will be
462 treated like a normal EOF condition on the handle.
463 The session in "$handle->{tls}" can still be examined in this
465 callback.
466 This callback will only be called on TLS shutdowns, not when
468 the underlying handle signals EOF.
469 json => JSON, JSON::PP or JSON::XS object
471 This is the json coder object used by the "json" read and write
472 types.
473 If you don't supply it, then AnyEvent::Handle will create and
475 use a suitable one (on demand), which will write and expect
476 UTF-8 encoded JSON texts (either using JSON::XS or JSON). The
477 written texts are guaranteed not to contain any newline
478 character.
479 For security reasons, this encoder will likely not handle
481 numbers and strings, only arrays and objects/hashes. The reason
482 is that originally JSON was self-delimited, but Dougles
483 Crockford thought it was a splendid idea to redefine JSON
484 incompatibly, so this is no longer true.
485 For protocols that used back-to-back JSON texts, this might
487 lead to run-ins, where two or more JSON texts will be
488 interpreted as one JSON text.
489 For this reason, if the default encoder uses JSON::XS, it will
491 default to not allowing anything but arrays and objects/hashes,
492 at least for the forseeable future (it will change at some
493 point). This might or might not be true for the JSON module, so
494 this might cause a security issue.
495 If you depend on either behaviour, you should create your own
497 json object and pass it in explicitly.
498 cbor => CBOR::XS object
500 This is the cbor coder object used by the "cbor" read and write
501 types.
502 If you don't supply it, then AnyEvent::Handle will create and
504 use a suitable one (on demand), which will write CBOR without
505 using extensions, if possible.
506 Note that you are responsible to depend on the CBOR::XS module
508 if you want to use this functionality, as AnyEvent does not
509 have a dependency on it itself.
510 $fh = $handle->fh
512 This method returns the file handle used to create the
513 AnyEvent::Handle object.
514 $handle->on_error ($cb)
516 Replace the current "on_error" callback (see the "on_error"
517 constructor argument).
518 $handle->on_eof ($cb)
520 Replace the current "on_eof" callback (see the "on_eof" constructor
521 argument).
522 $handle->on_timeout ($cb)
524 $handle->on_rtimeout ($cb)
525 $handle->on_wtimeout ($cb)
526 Replace the current "on_timeout", "on_rtimeout" or "on_wtimeout"
527 callback, or disables the callback (but not the timeout) if $cb =
528 "undef". See the "timeout" constructor argument and method.
529 $handle->autocork ($boolean)
531 Enables or disables the current autocork behaviour (see "autocork"
532 constructor argument). Changes will only take effect on the next
533 write.
534 $handle->no_delay ($boolean)
536 Enables or disables the "no_delay" setting (see constructor
537 argument of the same name for details).
538 $handle->keepalive ($boolean)
540 Enables or disables the "keepalive" setting (see constructor
541 argument of the same name for details).
542 $handle->oobinline ($boolean)
544 Enables or disables the "oobinline" setting (see constructor
545 argument of the same name for details).
546 $handle->on_starttls ($cb)
548 Replace the current "on_starttls" callback (see the "on_starttls"
549 constructor argument).
550 $handle->on_stoptls ($cb)
552 Replace the current "on_stoptls" callback (see the "on_stoptls"
553 constructor argument).
554 $handle->rbuf_max ($max_octets)
556 Configures the "rbuf_max" setting ("undef" disables it).
557 $handle->wbuf_max ($max_octets)
559 Configures the "wbuf_max" setting ("undef" disables it).
560 $handle->timeout ($seconds)
562 $handle->rtimeout ($seconds)
563 $handle->wtimeout ($seconds)
564 Configures (or disables) the inactivity timeout.
565 The timeout will be checked instantly, so this method might destroy
567 the handle before it returns.
568 $handle->timeout_reset
570 $handle->rtimeout_reset
571 $handle->wtimeout_reset
572 Reset the activity timeout, as if data was received or sent.
573 These methods are cheap to call.
575 WRITE QUEUE
577 AnyEvent::Handle manages two queues per handle, one for writing and one
578 for reading.
579 The write queue is very simple: you can add data to its end, and
581 AnyEvent::Handle will automatically try to get rid of it for you.
582 When data could be written and the write buffer is shorter then the low
584 water mark, the "on_drain" callback will be invoked once.
585 $handle->on_drain ($cb)
587 Sets the "on_drain" callback or clears it (see the description of
588 "on_drain" in the constructor).
589 This method may invoke callbacks (and therefore the handle might be
591 destroyed after it returns).
592 $handle->push_write ($data)
594 Queues the given scalar to be written. You can push as much data as
595 you want (only limited by the available memory and "wbuf_max"), as
596 "AnyEvent::Handle" buffers it independently of the kernel.
597 This method may invoke callbacks (and therefore the handle might be
599 destroyed after it returns).
600 $handle->push_write (type => @args)
602 Instead of formatting your data yourself, you can also let this
603 module do the job by specifying a type and type-specific arguments.
604 You can also specify the (fully qualified) name of a package, in
605 which case AnyEvent tries to load the package and then expects to
606 find the "anyevent_write_type" function inside (see "custom write
607 types", below).
608 Predefined types are (if you have ideas for additional types, feel
610 free to drop by and tell us):
611 netstring => $string
613 Formats the given value as netstring
614 (http://cr.yp.to/proto/netstrings.txt, this is not a
615 recommendation to use them).
616 packstring => $format, $data
618 An octet string prefixed with an encoded length. The encoding
619 $format uses the same format as a Perl "pack" format, but must
620 specify a single integer only (only one of "cCsSlLqQiInNvVjJw"
621 is allowed, plus an optional "!", "<" or ">" modifier).
622 json => $array_or_hashref
624 Encodes the given hash or array reference into a JSON object.
625 Unless you provide your own JSON object, this means it will be
626 encoded to JSON text in UTF-8.
627 The default encoder might or might not handle every type of
629 JSON value - it might be limited to arrays and objects for
630 security reasons. See the "json" constructor attribute for more
631 details.
632 JSON objects (and arrays) are self-delimiting, so if you only
634 use arrays and hashes, you can write JSON at one end of a
635 handle and read them at the other end without using any
636 additional framing.
637 The JSON text generated by the default encoder is guaranteed
639 not to contain any newlines: While this module doesn't need
640 delimiters after or between JSON texts to be able to read them,
641 many other languages depend on them.
642 A simple RPC protocol that interoperates easily with other
644 languages is to send JSON arrays (or objects, although arrays
645 are usually the better choice as they mimic how function
646 argument passing works) and a newline after each JSON text:
647 $handle->push_write (json => ["method", "arg1", "arg2"]); # whatever
649 $handle->push_write ("\012");
650 An AnyEvent::Handle receiver would simply use the "json" read
652 type and rely on the fact that the newline will be skipped as
653 leading whitespace:
654 $handle->push_read (json => sub { my $array = $_[1]; ... });
656 Other languages could read single lines terminated by a newline
658 and pass this line into their JSON decoder of choice.
659 cbor => $perl_scalar
661 Encodes the given scalar into a CBOR value. Unless you provide
662 your own CBOR::XS object, this means it will be encoded to a
663 CBOR string not using any extensions, if possible.
664 CBOR values are self-delimiting, so you can write CBOR at one
666 end of a handle and read them at the other end without using
667 any additional framing.
668 A simple nd very very fast RPC protocol that interoperates with
670 other languages is to send CBOR and receive CBOR values (arrays
671 are recommended):
672 $handle->push_write (cbor => ["method", "arg1", "arg2"]); # whatever
674 An AnyEvent::Handle receiver would simply use the "cbor" read
676 type:
677 $handle->push_read (cbor => sub { my $array = $_[1]; ... });
679 storable => $reference
681 Freezes the given reference using Storable and writes it to the
682 handle. Uses the "nfreeze" format.
683 $handle->push_shutdown
685 Sometimes you know you want to close the socket after writing your
686 data before it was actually written. One way to do that is to
687 replace your "on_drain" handler by a callback that shuts down the
688 socket (and set "low_water_mark" to 0). This method is a shorthand
689 for just that, and replaces the "on_drain" callback with:
690 sub { shutdown $_[0]{fh}, 1 }
692 This simply shuts down the write side and signals an EOF condition
694 to the the peer.
695 You can rely on the normal read queue and "on_eof" handling
697 afterwards. This is the cleanest way to close a connection.
698 This method may invoke callbacks (and therefore the handle might be
700 destroyed after it returns).
701 custom write types - Package::anyevent_write_type $handle, @args
703 Instead of one of the predefined types, you can also specify the
704 name of a package. AnyEvent will try to load the package and then
705 expects to find a function named "anyevent_write_type" inside. If
706 it isn't found, it progressively tries to load the parent package
707 until it either finds the function (good) or runs out of packages
708 (bad).
709 Whenever the given "type" is used, "push_write" will the function
711 with the handle object and the remaining arguments.
712 The function is supposed to return a single octet string that will
714 be appended to the write buffer, so you can mentally treat this
715 function as a "arguments to on-the-wire-format" converter.
716 Example: implement a custom write type "join" that joins the
718 remaining arguments using the first one.
719 $handle->push_write (My::Type => " ", 1,2,3);
721 # uses the following package, which can be defined in the "My::Type" or in
723 # the "My" modules to be auto-loaded, or just about anywhere when the
724 # My::Type::anyevent_write_type is defined before invoking it.
725 package My::Type;
727 sub anyevent_write_type {
729 my ($handle, $delim, @args) = @_;
730 join $delim, @args
732 }
733 READ QUEUE
735 AnyEvent::Handle manages two queues per handle, one for writing and one
736 for reading.
737 The read queue is more complex than the write queue. It can be used in
739 two ways, the "simple" way, using only "on_read" and the "complex" way,
740 using a queue.
741 In the simple case, you just install an "on_read" callback and whenever
743 new data arrives, it will be called. You can then remove some data (if
744 enough is there) from the read buffer ("$handle->rbuf"). Or you can
745 leave the data there if you want to accumulate more (e.g. when only a
746 partial message has been received so far), or change the read queue
747 with e.g. "push_read".
748 In the more complex case, you want to queue multiple callbacks. In this
750 case, AnyEvent::Handle will call the first queued callback each time
751 new data arrives (also the first time it is queued) and remove it when
752 it has done its job (see "push_read", below).
753 This way you can, for example, push three line-reads, followed by
755 reading a chunk of data, and AnyEvent::Handle will execute them in
756 order.
757 Example 1: EPP protocol parser. EPP sends 4 byte length info, followed
759 by the specified number of bytes which give an XML datagram.
760 # in the default state, expect some header bytes
762 $handle->on_read (sub {
763 # some data is here, now queue the length-header-read (4 octets)
764 shift->unshift_read (chunk => 4, sub {
765 # header arrived, decode
766 my $len = unpack "N", $_[1];
767 # now read the payload
769 shift->unshift_read (chunk => $len, sub {
770 my $xml = $_[1];
771 # handle xml
772 });
773 });
774 });
775 Example 2: Implement a client for a protocol that replies either with
777 "OK" and another line or "ERROR" for the first request that is sent,
778 and 64 bytes for the second request. Due to the availability of a
779 queue, we can just pipeline sending both requests and manipulate the
780 queue as necessary in the callbacks.
781 When the first callback is called and sees an "OK" response, it will
783 "unshift" another line-read. This line-read will be queued before the
784 64-byte chunk callback.
785 # request one, returns either "OK + extra line" or "ERROR"
787 $handle->push_write ("request 1\015\012");
788 # we expect "ERROR" or "OK" as response, so push a line read
790 $handle->push_read (line => sub {
791 # if we got an "OK", we have to _prepend_ another line,
792 # so it will be read before the second request reads its 64 bytes
793 # which are already in the queue when this callback is called
794 # we don't do this in case we got an error
795 if ($_[1] eq "OK") {
796 $_[0]->unshift_read (line => sub {
797 my $response = $_[1];
798 ...
799 });
800 }
801 });
802 # request two, simply returns 64 octets
804 $handle->push_write ("request 2\015\012");
805 # simply read 64 bytes, always
807 $handle->push_read (chunk => 64, sub {
808 my $response = $_[1];
809 ...
810 });
811 $handle->on_read ($cb)
813 This replaces the currently set "on_read" callback, or clears it
814 (when the new callback is "undef"). See the description of
815 "on_read" in the constructor.
816 This method may invoke callbacks (and therefore the handle might be
818 destroyed after it returns).
819 $handle->rbuf
821 Returns the read buffer (as a modifiable lvalue). You can also
822 access the read buffer directly as the "->{rbuf}" member, if you
823 want (this is much faster, and no less clean).
824 The only operation allowed on the read buffer (apart from looking
826 at it) is removing data from its beginning. Otherwise modifying or
827 appending to it is not allowed and will lead to hard-to-track-down
828 bugs.
829 NOTE: The read buffer should only be used or modified in the
831 "on_read" callback or when "push_read" or "unshift_read" are used
832 with a single callback (i.e. untyped). Typed "push_read" and
833 "unshift_read" methods will manage the read buffer on their own.
834 $handle->push_read ($cb)
836 $handle->unshift_read ($cb)
837 Append the given callback to the end of the queue ("push_read") or
838 prepend it ("unshift_read").
839 The callback is called each time some additional read data arrives.
841 It must check whether enough data is in the read buffer already.
843 If not enough data is available, it must return the empty list or a
845 false value, in which case it will be called repeatedly until
846 enough data is available (or an error condition is detected).
847 If enough data was available, then the callback must remove all
849 data it is interested in (which can be none at all) and return a
850 true value. After returning true, it will be removed from the
851 queue.
852 These methods may invoke callbacks (and therefore the handle might
854 be destroyed after it returns).
855 $handle->push_read (type => @args, $cb)
857 $handle->unshift_read (type => @args, $cb)
858 Instead of providing a callback that parses the data itself you can
859 chose between a number of predefined parsing formats, for chunks of
860 data, lines etc. You can also specify the (fully qualified) name of
861 a package, in which case AnyEvent tries to load the package and
862 then expects to find the "anyevent_read_type" function inside (see
863 "custom read types", below).
864 Predefined types are (if you have ideas for additional types, feel
866 free to drop by and tell us):
867 chunk => $octets, $cb->($handle, $data)
869 Invoke the callback only once $octets bytes have been read.
870 Pass the data read to the callback. The callback will never be
871 called with less data.
872 Example: read 2 bytes.
874 $handle->push_read (chunk => 2, sub {
876 say "yay " . unpack "H*", $_[1];
877 });
878 line => [$eol, ]$cb->($handle, $line, $eol)
880 The callback will be called only once a full line (including
881 the end of line marker, $eol) has been read. This line
882 (excluding the end of line marker) will be passed to the
883 callback as second argument ($line), and the end of line marker
884 as the third argument ($eol).
885 The end of line marker, $eol, can be either a string, in which
887 case it will be interpreted as a fixed record end marker, or it
888 can be a regex object (e.g. created by "qr"), in which case it
889 is interpreted as a regular expression.
890 The end of line marker argument $eol is optional, if it is
892 missing (NOT undef), then "qr|\015?\012|" is used (which is
893 good for most internet protocols).
894 Partial lines at the end of the stream will never be returned,
896 as they are not marked by the end of line marker.
897 regex => $accept[, $reject[, $skip], $cb->($handle, $data)
899 Makes a regex match against the regex object $accept and
900 returns everything up to and including the match. All the usual
901 regex variables ($1, %+ etc.) from the regex match are
902 available in the callback.
903 Example: read a single line terminated by '\n'.
905 $handle->push_read (regex => qr<\n>, sub { ... });
907 If $reject is given and not undef, then it determines when the
909 data is to be rejected: it is matched against the data when the
910 $accept regex does not match and generates an "EBADMSG" error
911 when it matches. This is useful to quickly reject wrong data
912 (to avoid waiting for a timeout or a receive buffer overflow).
913 Example: expect a single decimal number followed by whitespace,
915 reject anything else (not the use of an anchor).
916 $handle->push_read (regex => qr<^[0-9]+\s>, qr<[^0-9]>, sub { ... });
918 If $skip is given and not "undef", then it will be matched
920 against the receive buffer when neither $accept nor $reject
921 match, and everything preceding and including the match will be
922 accepted unconditionally. This is useful to skip large amounts
923 of data that you know cannot be matched, so that the $accept or
924 $reject regex do not have to start matching from the beginning.
925 This is purely an optimisation and is usually worth it only
926 when you expect more than a few kilobytes.
927 Example: expect a http header, which ends at
929 "\015\012\015\012". Since we expect the header to be very large
930 (it isn't in practice, but...), we use a skip regex to skip
931 initial portions. The skip regex is tricky in that it only
932 accepts something not ending in either \015 or \012, as these
933 are required for the accept regex.
934 $handle->push_read (regex =>
936 qr<\015\012\015\012>,
937 undef, # no reject
938 qr<^.*[^\015\012]>,
939 sub { ... });
940 netstring => $cb->($handle, $string)
942 A netstring (http://cr.yp.to/proto/netstrings.txt, this is not
943 an endorsement).
944 Throws an error with $! set to EBADMSG on format violations.
946 packstring => $format, $cb->($handle, $string)
948 An octet string prefixed with an encoded length. The encoding
949 $format uses the same format as a Perl "pack" format, but must
950 specify a single integer only (only one of "cCsSlLqQiInNvVjJw"
951 is allowed, plus an optional "!", "<" or ">" modifier).
952 For example, DNS over TCP uses a prefix of "n" (2 octet network
954 order), EPP uses a prefix of "N" (4 octtes).
955 Example: read a block of data prefixed by its length in BER-
957 encoded format (very efficient).
958 $handle->push_read (packstring => "w", sub {
960 my ($handle, $data) = @_;
961 });
962 json => $cb->($handle, $hash_or_arrayref)
964 Reads a JSON object or array, decodes it and passes it to the
965 callback. When a parse error occurs, an "EBADMSG" error will be
966 raised.
967 If a "json" object was passed to the constructor, then that
969 will be used for the final decode, otherwise it will create a
970 JSON::XS or JSON::PP coder object expecting UTF-8.
971 This read type uses the incremental parser available with JSON
973 version 2.09 (and JSON::XS version 2.2) and above.
974 Since JSON texts are fully self-delimiting, the "json" read and
976 write types are an ideal simple RPC protocol: just exchange
977 JSON datagrams. See the "json" write type description, above,
978 for an actual example.
979 cbor => $cb->($handle, $scalar)
981 Reads a CBOR value, decodes it and passes it to the callback.
982 When a parse error occurs, an "EBADMSG" error will be raised.
983 If a CBOR::XS object was passed to the constructor, then that
985 will be used for the final decode, otherwise it will create a
986 CBOR coder without enabling any options.
987 You have to provide a dependency to CBOR::XS on your own: this
989 module will load the CBOR::XS module, but AnyEvent does not
990 depend on it itself.
991 Since CBOR values are fully self-delimiting, the "cbor" read
993 and write types are an ideal simple RPC protocol: just exchange
994 CBOR datagrams. See the "cbor" write type description, above,
995 for an actual example.
996 storable => $cb->($handle, $ref)
998 Deserialises a Storable frozen representation as written by the
999 "storable" write type (BER-encoded length prefix followed by
1000 nfreeze'd data).
1001 Raises "EBADMSG" error if the data could not be decoded.
1003 tls_detect => $cb->($handle, $detect, $major, $minor)
1005 Checks the input stream for a valid SSL or TLS handshake
1006 TLSPaintext record without consuming anything. Only SSL version
1007 3 or higher is handled, up to the fictituous protocol 4.x (but
1008 both SSL3+ and SSL2-compatible framing is supported).
1009 If it detects that the input data is likely TLS, it calls the
1011 callback with a true value for $detect and the (on-wire) TLS
1012 version as second and third argument ($major is 3, and $minor
1013 is 0..4 for SSL 3.0, TLS 1.0, 1.1, 1.2 and 1.3, respectively).
1014 If it detects the input to be definitely not TLS, it calls the
1015 callback with a false value for $detect.
1016 The callback could use this information to decide whether or
1018 not to start TLS negotiation.
1019 In all cases the data read so far is passed to the following
1021 read handlers.
1022 Usually you want to use the "tls_autostart" read type instead.
1024 If you want to design a protocol that works in the presence of
1026 TLS dtection, make sure that any non-TLS data doesn't start
1027 with the octet 22 (ASCII SYN, 16 hex) or 128-255 (i.e. highest
1028 bit set). The checks this read type does are a bit more strict,
1029 but might losen in the future to accomodate protocol changes.
1030 This read type does not rely on AnyEvent::TLS (and thus, not on
1032 Net::SSLeay).
1033 tls_autostart => [$tls_ctx, ]$tls
1035 Tries to detect a valid SSL or TLS handshake. If one is
1036 detected, it tries to start tls by calling "starttls" with the
1037 given arguments.
1038 In practise, $tls must be "accept", or a Net::SSLeay context
1040 that has been configured to accept, as servers do not normally
1041 send a handshake on their own and ths cannot be detected in
1042 this way.
1043 See "tls_detect" above for more details.
1045 Example: give the client a chance to start TLS before accepting
1047 a text line.
1048 $hdl->push_read (tls_autostart => "accept");
1050 $hdl->push_read (line => sub {
1051 print "received ", ($_[0]{tls} ? "encrypted" : "cleartext"), " <$_[1]>\n";
1052 });
1053 custom read types - Package::anyevent_read_type $handle, $cb, @args
1055 Instead of one of the predefined types, you can also specify the
1056 name of a package. AnyEvent will try to load the package and then
1057 expects to find a function named "anyevent_read_type" inside. If it
1058 isn't found, it progressively tries to load the parent package
1059 until it either finds the function (good) or runs out of packages
1060 (bad).
1061 Whenever this type is used, "push_read" will invoke the function
1063 with the handle object, the original callback and the remaining
1064 arguments.
1065 The function is supposed to return a callback (usually a closure)
1067 that works as a plain read callback (see "->push_read ($cb)"), so
1068 you can mentally treat the function as a "configurable read type to
1069 read callback" converter.
1070 It should invoke the original callback when it is done reading
1072 (remember to pass $handle as first argument as all other callbacks
1073 do that, although there is no strict requirement on this).
1074 For examples, see the source of this module (perldoc -m
1076 AnyEvent::Handle, search for "register_read_type")).
1077 $handle->stop_read
1079 $handle->start_read
1080 In rare cases you actually do not want to read anything from the
1081 socket. In this case you can call "stop_read". Neither "on_read"
1082 nor any queued callbacks will be executed then. To start reading
1083 again, call "start_read".
1084 Note that AnyEvent::Handle will automatically "start_read" for you
1086 when you change the "on_read" callback or push/unshift a read
1087 callback, and it will automatically "stop_read" for you when
1088 neither "on_read" is set nor there are any read requests in the
1089 queue.
1090 In older versions of this module (<= 5.3), these methods had no
1092 effect, as TLS does not support half-duplex connections. In current
1093 versions they work as expected, as this behaviour is required to
1094 avoid certain resource attacks, where the program would be forced
1095 to read (and buffer) arbitrary amounts of data before being able to
1096 send some data. The drawback is that some readings of the the
1097 SSL/TLS specifications basically require this attack to be working,
1098 as SSL/TLS implementations might stall sending data during a
1099 rehandshake.
1100 As a guideline, during the initial handshake, you should not stop
1102 reading, and as a client, it might cause problems, depending on
1103 your application.
1104 $handle->starttls ($tls[, $tls_ctx])
1106 Instead of starting TLS negotiation immediately when the
1107 AnyEvent::Handle object is created, you can also do that at a later
1108 time by calling "starttls". See the "tls" constructor argument for
1109 general info.
1110 Starting TLS is currently an asynchronous operation - when you push
1112 some write data and then call "->starttls" then TLS negotiation
1113 will start immediately, after which the queued write data is then
1114 sent. This might change in future versions, so best make sure you
1115 have no outstanding write data when calling this method.
1116 The first argument is the same as the "tls" constructor argument
1118 (either "connect", "accept" or an existing Net::SSLeay object).
1119 The second argument is the optional "AnyEvent::TLS" object that is
1121 used when AnyEvent::Handle has to create its own TLS connection
1122 object, or a hash reference with "key => value" pairs that will be
1123 used to construct a new context.
1124 The TLS connection object will end up in "$handle->{tls}", the TLS
1126 context in "$handle->{tls_ctx}" after this call and can be used or
1127 changed to your liking. Note that the handshake might have already
1128 started when this function returns.
1129 Due to bugs in OpenSSL, it might or might not be possible to do
1131 multiple handshakes on the same stream. It is best to not attempt
1132 to use the stream after stopping TLS.
1133 This method may invoke callbacks (and therefore the handle might be
1135 destroyed after it returns).
1136 $handle->stoptls
1138 Shuts down the SSL connection - this makes a proper EOF handshake
1139 by sending a close notify to the other side, but since OpenSSL
1140 doesn't support non-blocking shut downs, it is not guaranteed that
1141 you can re-use the stream afterwards.
1142 This method may invoke callbacks (and therefore the handle might be
1144 destroyed after it returns).
1145 $handle->resettls
1147 This rarely-used method simply resets and TLS state on the handle,
1148 usually causing data loss.
1149 One case where it may be useful is when you want to skip over the
1151 data in the stream but you are not interested in interpreting it,
1152 so data loss is no concern.
1153 $handle->destroy
1155 Shuts down the handle object as much as possible - this call
1156 ensures that no further callbacks will be invoked and as many
1157 resources as possible will be freed. Any method you will call on
1158 the handle object after destroying it in this way will be silently
1159 ignored (and it will return the empty list).
1160 Normally, you can just "forget" any references to an
1162 AnyEvent::Handle object and it will simply shut down. This works in
1163 fatal error and EOF callbacks, as well as code outside. It does NOT
1164 work in a read or write callback, so when you want to destroy the
1165 AnyEvent::Handle object from within such an callback. You MUST call
1166 "->destroy" explicitly in that case.
1167 Destroying the handle object in this way has the advantage that
1169 callbacks will be removed as well, so if those are the only
1170 reference holders (as is common), then one doesn't need to do
1171 anything special to break any reference cycles.
1172 The handle might still linger in the background and write out
1174 remaining data, as specified by the "linger" option, however.
1175 $handle->destroyed
1177 Returns false as long as the handle hasn't been destroyed by a call
1178 to "->destroy", true otherwise.
1179 Can be useful to decide whether the handle is still valid after
1181 some callback possibly destroyed the handle. For example,
1182 "->push_write", "->starttls" and other methods can call user
1183 callbacks, which in turn can destroy the handle, so work can be
1184 avoided by checking sometimes:
1185 $hdl->starttls ("accept");
1187 return if $hdl->destroyed;
1188 $hdl->push_write (...
1189 Note that the call to "push_write" will silently be ignored if the
1191 handle has been destroyed, so often you can just ignore the
1192 possibility of the handle being destroyed.
1193 AnyEvent::Handle::TLS_CTX
1195 This function creates and returns the AnyEvent::TLS object used by
1196 default for TLS mode.
1197 The context is created by calling AnyEvent::TLS without any
1199 arguments.
1200
1202 I "undef" the AnyEvent::Handle reference inside my callback and still
1203 get further invocations!
1204 That's because AnyEvent::Handle keeps a reference to itself when
1205 handling read or write callbacks.
1206 It is only safe to "forget" the reference inside EOF or error
1208 callbacks, from within all other callbacks, you need to explicitly
1209 call the "->destroy" method.
1210 Why is my "on_eof" callback never called?
1212 Probably because your "on_error" callback is being called instead:
1213 When you have outstanding requests in your read queue, then an EOF
1214 is considered an error as you clearly expected some data.
1215 To avoid this, make sure you have an empty read queue whenever your
1217 handle is supposed to be "idle" (i.e. connection closes are O.K.).
1218 You can set an "on_read" handler that simply pushes the first read
1219 requests in the queue.
1220 See also the next question, which explains this in a bit more
1222 detail.
1223 How can I serve requests in a loop?
1225 Most protocols consist of some setup phase (authentication for
1226 example) followed by a request handling phase, where the server
1227 waits for requests and handles them, in a loop.
1228 There are two important variants: The first (traditional, better)
1230 variant handles requests until the server gets some QUIT command,
1231 causing it to close the connection first (highly desirable for a
1232 busy TCP server). A client dropping the connection is an error,
1233 which means this variant can detect an unexpected detection close.
1234 To handle this case, always make sure you have a non-empty read
1236 queue, by pushing the "read request start" handler on it:
1237 # we assume a request starts with a single line
1239 my @start_request; @start_request = (line => sub {
1240 my ($hdl, $line) = @_;
1241 ... handle request
1243 # push next request read, possibly from a nested callback
1245 $hdl->push_read (@start_request);
1246 });
1247 # auth done, now go into request handling loop
1249 # now push the first @start_request
1250 $hdl->push_read (@start_request);
1251 By always having an outstanding "push_read", the handle always
1253 expects some data and raises the "EPIPE" error when the connction
1254 is dropped unexpectedly.
1255 The second variant is a protocol where the client can drop the
1257 connection at any time. For TCP, this means that the server machine
1258 may run out of sockets easier, and in general, it means you cannot
1259 distinguish a protocl failure/client crash from a normal connection
1260 close. Nevertheless, these kinds of protocols are common (and
1261 sometimes even the best solution to the problem).
1262 Having an outstanding read request at all times is possible if you
1264 ignore "EPIPE" errors, but this doesn't help with when the client
1265 drops the connection during a request, which would still be an
1266 error.
1267 A better solution is to push the initial request read in an
1269 "on_read" callback. This avoids an error, as when the server
1270 doesn't expect data (i.e. is idly waiting for the next request, an
1271 EOF will not raise an error, but simply result in an "on_eof"
1272 callback. It is also a bit slower and simpler:
1273 # auth done, now go into request handling loop
1275 $hdl->on_read (sub {
1276 my ($hdl) = @_;
1277 # called each time we receive data but the read queue is empty
1279 # simply start read the request
1280 $hdl->push_read (line => sub {
1282 my ($hdl, $line) = @_;
1283 ... handle request
1285 # do nothing special when the request has been handled, just
1287 # let the request queue go empty.
1288 });
1289 });
1290 I get different callback invocations in TLS mode/Why can't I pause
1292 reading?
1293 Unlike, say, TCP, TLS connections do not consist of two independent
1294 communication channels, one for each direction. Or put differently,
1295 the read and write directions are not independent of each other:
1296 you cannot write data unless you are also prepared to read, and
1297 vice versa.
1298 This means that, in TLS mode, you might get "on_error" or "on_eof"
1300 callback invocations when you are not expecting any read data - the
1301 reason is that AnyEvent::Handle always reads in TLS mode.
1302 During the connection, you have to make sure that you always have a
1304 non-empty read-queue, or an "on_read" watcher. At the end of the
1305 connection (or when you no longer want to use it) you can call the
1306 "destroy" method.
1307 How do I read data until the other side closes the connection?
1309 If you just want to read your data into a perl scalar, the easiest
1310 way to achieve this is by setting an "on_read" callback that does
1311 nothing, clearing the "on_eof" callback and in the "on_error"
1312 callback, the data will be in "$_[0]{rbuf}":
1313 $handle->on_read (sub { });
1315 $handle->on_eof (undef);
1316 $handle->on_error (sub {
1317 my $data = delete $_[0]{rbuf};
1318 });
1319 Note that this example removes the "rbuf" member from the handle
1321 object, which is not normally allowed by the API. It is expressly
1322 permitted in this case only, as the handle object needs to be
1323 destroyed afterwards.
1324 The reason to use "on_error" is that TCP connections, due to
1326 latencies and packets loss, might get closed quite violently with
1327 an error, when in fact all data has been received.
1328 It is usually better to use acknowledgements when transferring
1330 data, to make sure the other side hasn't just died and you got the
1331 data intact. This is also one reason why so many internet protocols
1332 have an explicit QUIT command.
1333 I don't want to destroy the handle too early - how do I wait until all
1335 data has been written?
1336 After writing your last bits of data, set the "on_drain" callback
1337 and destroy the handle in there - with the default setting of
1338 "low_water_mark" this will be called precisely when all data has
1339 been written to the socket:
1340 $handle->push_write (...);
1342 $handle->on_drain (sub {
1343 AE::log debug => "All data submitted to the kernel.";
1344 undef $handle;
1345 });
1346 If you just want to queue some data and then signal EOF to the
1348 other side, consider using "->push_shutdown" instead.
1349 I want to contact a TLS/SSL server, I don't care about security.
1351 If your TLS server is a pure TLS server (e.g. HTTPS) that only
1352 speaks TLS, connect to it and then create the AnyEvent::Handle with
1353 the "tls" parameter:
1354 tcp_connect $host, $port, sub {
1356 my ($fh) = @_;
1357 my $handle = new AnyEvent::Handle
1359 fh => $fh,
1360 tls => "connect",
1361 on_error => sub { ... };
1362 $handle->push_write (...);
1364 };
1365 I want to contact a TLS/SSL server, I do care about security.
1367 Then you should additionally enable certificate verification,
1368 including peername verification, if the protocol you use supports
1369 it (see AnyEvent::TLS, "verify_peername").
1370 E.g. for HTTPS:
1372 tcp_connect $host, $port, sub {
1374 my ($fh) = @_;
1375 my $handle = new AnyEvent::Handle
1377 fh => $fh,
1378 peername => $host,
1379 tls => "connect",
1380 tls_ctx => { verify => 1, verify_peername => "https" },
1381 ...
1382 Note that you must specify the hostname you connected to (or
1384 whatever "peername" the protocol needs) as the "peername" argument,
1385 otherwise no peername verification will be done.
1386 The above will use the system-dependent default set of trusted CA
1388 certificates. If you want to check against a specific CA, add the
1389 "ca_file" (or "ca_cert") arguments to "tls_ctx":
1390 tls_ctx => {
1392 verify => 1,
1393 verify_peername => "https",
1394 ca_file => "my-ca-cert.pem",
1395 },
1396 I want to create a TLS/SSL server, how do I do that?
1398 Well, you first need to get a server certificate and key. You have
1399 three options: a) ask a CA (buy one, use cacert.org etc.) b) create
1400 a self-signed certificate (cheap. check the search engine of your
1401 choice, there are many tutorials on the net) or c) make your own CA
1402 (tinyca2 is a nice program for that purpose).
1403 Then create a file with your private key (in PEM format, see
1405 AnyEvent::TLS), followed by the certificate (also in PEM format).
1406 The file should then look like this:
1407 -----BEGIN RSA PRIVATE KEY-----
1409 ...header data
1410 ... lots of base64'y-stuff
1411 -----END RSA PRIVATE KEY-----
1412 -----BEGIN CERTIFICATE-----
1414 ... lots of base64'y-stuff
1415 -----END CERTIFICATE-----
1416 The important bits are the "PRIVATE KEY" and "CERTIFICATE" parts.
1418 Then specify this file as "cert_file":
1419 tcp_server undef, $port, sub {
1421 my ($fh) = @_;
1422 my $handle = new AnyEvent::Handle
1424 fh => $fh,
1425 tls => "accept",
1426 tls_ctx => { cert_file => "my-server-keycert.pem" },
1427 ...
1428 When you have intermediate CA certificates that your clients might
1430 not know about, just append them to the "cert_file".
1431
1433 In many cases, you might want to subclass AnyEvent::Handle.
1434 To make this easier, a given version of AnyEvent::Handle uses these
1436 conventions:
1437 • all constructor arguments become object members.
1439 At least initially, when you pass a "tls"-argument to the
1441 constructor it will end up in "$handle->{tls}". Those members might
1442 be changed or mutated later on (for example "tls" will hold the TLS
1443 connection object).
1444 • other object member names are prefixed with an "_".
1446 All object members not explicitly documented (internal use) are
1448 prefixed with an underscore character, so the remaining
1449 non-"_"-namespace is free for use for subclasses.
1450 • all members not documented here and not prefixed with an underscore
1452 are free to use in subclasses.
1453 Of course, new versions of AnyEvent::Handle may introduce more
1455 "public" member variables, but that's just life. At least it is
1456 documented.
1457
1459 Robin Redeker "<elmex at ta-sa.org>", Marc Lehmann
1460 <schmorp@schmorp.de>.
1461perl v5.36.0 2022-07-22 AnyEvent::Handle(3)