/ 
Linux-Event-0.112
/ Linux::Event::IO::Sock::Dgram

NAME

Linux::Event::IO::Sock::Dgram - asynchronous Linux SOCK_DGRAM I/O

SYNOPSIS

use v5.36;
use Linux::Event::Loop;
use Linux::Event::IO::Sock::Dgram;

my $loop = Linux::Event::Loop->new;
my $server = Linux::Event::IO::Sock::Dgram->new(
    loop => $loop,
    host => '127.0.0.1',
    port => 9999,
    on_datagram => sub ($socket, $payload, $peer) {
        $socket->send($payload, to => $peer);
    },
);
$loop->run;

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.

CALLBACKS, SUBCLASSING, AND TUNING

new and connect accept on_datagram, on_ready, on_drain, on_error, and on_close as constructor coderefs. Closures are convenient for one socket and can capture lexical application state.

Subclassing remains valuable when sockets share packet policy, tuning, and named callbacks. datagram_options centralizes packet limits, fairness, queue watermarks, and socket policy. configure_socket is the cached subclass hook for uncommon Linux socket configuration. Constructor values and callbacks override class policy for one object. Linux::Event resolves all of this at construction rather than looking up methods during packet delivery.

Datagrams already have kernel packet boundaries, so byte-stream framers and TLS policy do not apply to this class.

datagram_options

Define datagram_options as a class method on the Dgram subclass. It returns key/value pairs, or one hash reference:

package ServiceDgram;
use parent 'Linux::Event::IO::Sock::Dgram';

sub datagram_options ($class) {
    return (
        max_datagram_size      => 32_768,
        max_datagrams_per_tick => 128,
        receive_buffer         => 1_048_576,
    );
}

sub on_datagram ($socket, $payload, $peer) { ... }

Constructor values override this cached class policy for one socket. The complete option set is:

  • max_datagram_size (default 65,535)

    Largest accepted packet, from 1 through 16,777,216 bytes. An oversized packet is rejected whole rather than delivered as a truncated prefix.

  • max_datagrams_per_tick (default 256)

    Non-negative receive fairness limit. Zero drains until EAGAIN and is required when edge_triggered is enabled.

  • edge_triggered (default 0)

    Boolean 0 or 1 selecting edge-triggered receive readiness.

  • high_watermark (default 1,048,576)

    Non-negative queued-payload byte level at which send begins returning false while still accepting the datagram.

  • low_watermark (default 262,144)

    Non-negative queued-payload byte level at or below which on_drain fires after high-watermark backpressure. It must not exceed high_watermark.

  • max_pending_bytes (default 0)

    Hard non-negative queued-payload byte limit. Zero means unbounded.

  • max_pending_datagrams (default 0)

    Hard non-negative queued-datagram count limit. Zero means unbounded.

  • reuseaddr (default 0)

    Boolean 0 or 1 controlling SO_REUSEADDR.

  • reuseport (default 0)

    Boolean 0 or 1 controlling SO_REUSEPORT.

  • broadcast (default 0)

    Boolean 0 or 1 controlling SO_BROADCAST.

  • v6only (default unspecified)

    Optional boolean 0 or 1 controlling IPV6_V6ONLY on IPv6 sockets.

  • send_buffer (default unspecified)

    Optional positive integer requested SO_SNDBUF size, at most 2,147,483,647.

  • receive_buffer (default unspecified)

    Optional positive integer requested SO_RCVBUF size, at most 2,147,483,647.

bind_device, Unix path ownership options, and owns_socket are constructor policy rather than datagram_options keys. configure_socket is the cached hook for uncommon Linux socket configuration.

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 subclass may define, or construction may receive:

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. Its complete contract appears near the top of this document. Unix path ownership, permissions, and interface binding remain per-object constructor policy.

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.