AnyEve...le::UDP(3pm)

💖 AnyEvent::Handle::UDP 💖

okay bestie, so this is AnyEvent::Handle::UDP — client/server UDP handles for AnyEvent, living its best life in the User Contributed Perl Documentation section (that's the 3pm part, iykyk).

---

✨ VERSION ✨

version 0.050 — yes, we're on the 0.050 era, iconic behavior honestly.

---

🌸 SYNOPSIS 🌸

here's the vibe, a whole echo server in like six lines, no cap:

my $echo_server = AnyEvent::Handle::UDP->new(
    bind => ['0.0.0.0', 4000],
    on_recv => sub {
        my ($data, $ae_handle, $client_addr) = @_;
        $ae_handle->push_send($data, $client_addr);
    },
);

it just… receives stuff and throws it right back. slay.

---

🦋 DESCRIPTION 🦋

This module is an abstraction around UDP sockets for use with AnyEvent. that's the whole thing, that's the assignment 💅

---

🎀 ATTRIBUTES 🎀

🫶 on_recv

The callback for when a package arrives. It takes three arguments: the datagram, the handle, and the address the datagram was received from. three lil guys, all important.

😭 on_error

The callback for when an error occurs. It takes three arguments: the handle, a boolean saying whether the error is fatal or not, and the error message. read that boolean, bestie, it matters.

✨ on_bind

The callback for when the bind has been performed (this may be after object construction if address lookup is involved). so like… don't assume it already happened, okay?

🌈 on_connect

The callback for when the connect has been performed (this may be after object construction if address lookup is involved). same energy as above, different verb.

🌸 on_drain

This sets the callback that is called when the send buffer becomes empty. The callback takes the handle as its only argument. one single argument, we love a low-maintenance callback.

💅 autoflush

Always attempt to send data to the operating system immediately, without waiting for the loop to indicate the filehandle is write-ready. impatient? valid. this is the impatient button.

🍓 receive_size

The buffer size for the receiving, in bytes. It defaults to 1500, which is slightly more than the MTA on ethernet. very on-the-nose default, honestly obsessed.

🧚 family

Sets the socket family. The default is 0, which means either IPv4 or IPv6. The values 4 and 6 mean IPv4 and IPv6 respectively.

⭐ fh

The underlying filehandle. Note that this doesn't cooperate with the connect and bind parameters. like, they do not get along. do not introduce them.

💜 reuse_addr

If true will enable quick reuse of the bound address.

🎀 timeout, rtimeout, wtimeout

If non-zero, then these enables an "inactivity" timeout: whenever this many seconds pass without a successful read or write on the underlying file handle (or a call to timeout_reset), the on_timeout callback will be invoked (and if that one is missing, a non-fatal ETIMEDOUT error will be raised).

There are three variants of the timeouts that work independently of each other, for both read and write (triggered when nothing was read OR written), just read (triggered when nothing was read), and just write: timeout, rtimeout and wtimeout, with corresponding callbacks on_timeout, on_rtimeout and on_wtimeout, and reset functions timeout_reset, rtimeout_reset, and wtimeout_reset.

⚠️ note that timeout processing is active even when you do not have any outstanding read or write requests: If you plan to keep the connection idle then you should disable the timeout temporarily or ignore the timeout in the corresponding on_timeout callback, in which case AnyEvent::Handle will simply restart the timeout. yeah. it's watching. it's always watching. 👀

Calling clear_timeout (or setting it to zero, which does the same) disables the corresponding timeout.

🦋 on_timeout, on_rtimeout, on_wtimeout

The callback that's called whenever the inactivity timeout passes. If you return from this callback, then the timeout will be reset as if some activity had happened, so this condition is not fatal in any way. you literally just have to return and everything's fine, periodt.

---

👑 METHODS 👑

🌟 new

Create a new UDP handle. As arguments it accepts any attribute, as well as these two:

• connect — Set the address to which datagrams are sent by default, and the only address from which datagrams are received. It must be either a packed sockaddr struct or an arrayref containing a hostname and a portnumber.
• bind — The address to bind the socket to. It must be either a packed sockaddr struct or an arrayref containing a hostname and a portnumber.

All except on_recv are optional, though using either connect or bind (or both) is strongly recommended unless you give it a connected/bound fh. like please. do that. 🙈

🎀 bind_to($address)

Bind to the specified addres. Note that a bound socket may be rebound to another address. $address must be in the same form as the bind argument to new. (yes, "addres" — we're keeping the typo, it's part of the lore 💖)

💫 connect_to($address)

Connect to the specified address. Note that a connected socket may be reconnected to another address. $address must be in the same form as the connect argument to new.

🔥 push_send($message, $to = undef, $cv = AnyEvent::CondVar->new)

Try to send a message. If a socket is not connected a receptient address must also be given. If it is connected giving a receptient may not work as expected, depending on your platform. It returns $cv, which will become true when $message is sent. the $cv is your little "did it go tho" receipt 💅

🧚 timeout_reset, rtimeout_reset, wtimeout_reset

Reset the activity timeout, as if data was received or sent.

🌸 sockname

Get the local address, per getsockname.

🌈 peername

Get the peer's address, per getpeername.

💀 destroy

Destroy the handle. bye bestie 🫶

---

🚫 BACKWARDS COMPATIBILITY 🚫

This module is not backwards compatible in any way with the defunct previous module of the same name by Jan Henning Thorsen. not even a little. zero. nada. it's giving total rebrand.

---

✍️ AUTHOR ✍️

Leon Timmermans <leont@cpan.org>

---

📜 COPYRIGHT AND LICENSE 📜

This software is copyright (c) 2011 by Leon Timmermans.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

and that's the whole page, bestie!! this was perl v5.36.0, dated 2022-11-27, and it lives at AnyEve...le::UDP(3pm) — go forth and UDP responsibly, mwah 💖✨🎀