NAME
Linux::Event::IO::Sock::Dgram - asynchronous Linux SOCK_DGRAM I/O
SYNOPSIS
package EchoDgram;
use parent 'Linux::Event::IO::Sock::Dgram';
sub on_datagram ($socket, $payload, $peer) {
$socket->send($payload, to => $peer);
}
package main;
my $server = $loop->add(EchoDgram->new(
host => '127.0.0.1',
port => 9999,
));DESCRIPTION
Linux::Event::IO::Sock::Dgram is the public class for Linux SOCK_DGRAM sockets. It preserves kernel packet boundaries and peer addresses rather than forcing datagrams through the ordered-byte framing engine.
UDP over IPv4 or IPv6 and Unix-domain datagram sockets use the same class; address family is constructor policy rather than a public type hierarchy.
BOUND AND CONNECTED FORMS
new creates or adopts an unconnected packet socket. For UDP:
my $server = EchoDgram->new(
host => '0.0.0.0',
port => 9999,
);connect installs a default peer:
my $client = EchoDgram->connect(
host => 'collector.example.com',
port => 9000,
);Hostnames for connected UDP are resolved asynchronously. Numeric Internet addresses and Unix paths bypass resolution. Unix-domain sockets use unix for the bound or peer path and may use local_unix for a connected client's local reply path.
An adopted fh must be an IPv4, IPv6, or Unix datagram socket. Created handles are owned by the object; adopted handles remain caller-owned unless owns_socket is true.
loop => $loop attaches immediately. Detached objects may be added later with $loop->add($socket).
CALLBACKS
A concrete subclass defines:
sub on_datagram ($socket, $payload, $peer) { ... }Each callback represents exactly one kernel datagram. $peer is a lazy Linux::Event::Address. Zero-length datagrams are valid.
Optional on_ready, on_drain, on_error, and on_close callbacks cover lifecycle and output flow control. Datagram I/O errors and queue-limit errors do not automatically invent byte-stream EOF semantics.
SENDING
For a connected socket:
$socket->send($payload);For an unconnected socket:
$socket->send($payload, to => $peer);One send call is one packet. If output would block, the complete datagram is queued and retried atomically. High/low byte watermarks provide cooperative backpressure. max_pending_bytes and max_pending_datagrams provide hard queue bounds without splitting an accepted packet.
INPUT LIMITS AND FAIRNESS
max_datagram_size bounds accepted packet size. Native recvmsg uses MSG_TRUNC so an oversized packet can be rejected whole instead of delivering a misleading prefix. max_datagrams_per_tick bounds level-triggered receive work for fairness; zero drains to EAGAIN and is required for edge-triggered operation.
SOCKET POLICY
datagram_options caches packet limits, watermarks, fairness, and common socket policy per subclass. Internet sockets support options such as reuseaddr, reuseport, broadcast, optional v6only, bind_device, and socket buffers where applicable. Unix sockets support path ownership and permissions. Constructor values override class policy for one object.
METHODS AND LIFECYCLE
local and peer expose lazy address values where meaningful. is_connected, state, pending_bytes, and related queue accessors expose current state.
close terminates the object and releases owned socket/path resources. detach returns the still-open handle, suppresses Unix path removal, and is a terminal ownership transfer.
SEE ALSO
Linux::Event::IO::Sock::Stream, Linux::Event::Address, docs/DGRAM-DESIGN.md, docs/SOCKET-CONFIGURATION.md.