/ 
Linux-Event-0.117
/ Linux::Event::Error

NAME

Linux::Event::Error - Structured error information from Linux::Event

SYNOPSIS

on_error => sub ($self, $error) {
    warn $error->type . ': ' . $error->message . "\n";

    if (defined(my $errno = $error->errno)) {
        warn "errno=$errno\n";
    }
}

DESCRIPTION

Linux::Event::Error represents a structured Linux::Event failure.

Instead of forcing application code to parse an error string, it provides separate fields such as:

type
operation
errno
message

and additional context when a particular error needs it.

For example, a failed connection might contain:

type       connect
operation  connect
errno      111
message    Connection refused
host       127.0.0.1
port       9
attempts   2

Applications can therefore make decisions from the structured fields while still using the object directly as a readable diagnostic.

WHERE ERROR OBJECTS APPEAR

Linux::Event::Error objects are used in two main ways.

Error callbacks

Many Linux::Event resources provide an on_error callback:

on_error => sub ($self, $error) {
    ...
}

For example, Stream, Listener, Datagram, and Process can report asynchronous runtime failures this way.

Thrown errors

Some synchronous setup or API failures throw a Linux::Event::Error directly.

For example:

my $ok = eval {
    $process->signal($signal);
    1;
};

if (!$ok) {
    my $error = $@;

    if (ref($error) && $error->isa('Linux::Event::Error')) {
        say $error->operation;
    }
}

Whether an error is thrown or delivered through a callback depends on the API and on when the failure occurs.

The Error object itself uses the same structured model in either case.

STRINGIFICATION

Error objects stringify automatically.

For example:

warn "$error\n";

might produce:

connect: Connection refused (errno=111)

The string form is intended for people.

Do not parse it to make application decisions.

Use accessors instead:

if ($error->type eq 'timeout') {
    ...
}

COMMON FIELDS

The following fields are the most broadly useful.

type

my $type = $error->type;

Return the broad category of failure.

Examples currently used by Linux::Event include:

io
framing
output_limit
resolve
socket
socket_configuration
connect
timeout
setup
accept
resource
listener
callback
datagram_size
process
process_io
tls

The set may grow as Linux::Event gains capabilities.

Applications should normally handle the error types they care about and keep a general fallback for unfamiliar values.

For example:

if ($error->type eq 'timeout') {
    retry_later();
}
else {
    warn "$error\n";
}

operation

my $operation = $error->operation;

Return the operation that was being performed when the failure occurred.

Examples include:

connect
bind
setsockopt
write
write_stdin
receive
waitid
signal
idle
read

operation is more specific than type.

For example, several different socket-configuration failures may all have:

type => 'socket_configuration'

while operation identifies whether the failing action was bind, setsockopt, or another configuration step.

operation may be undefined when no useful operation label applies.

message

my $message = $error->message;

Return the human-readable description of the failure.

For example:

Connection refused

or:

pending output would exceed 16384 bytes

The message is useful for logs and diagnostics.

Application logic should prefer structured fields whenever possible.

errno

my $errno = $error->errno;

Return the numeric system errno when the failure corresponds to a system error.

For example:

if (defined(my $errno = $error->errno)) {
    say "system errno: $errno";
}

Not every Linux::Event error originates from a syscall, so errno may be undefined.

SOCKET CONFIGURATION DETAILS

option

my $option = $error->option;

For socket_configuration errors, this may identify the socket option involved.

For example:

type      => 'socket_configuration'
operation => 'setsockopt'
option    => 'v6only'

For unrelated errors, option is normally undefined.

ADDRESS CONTEXT

Some connection, listener, or datagram failures include address information.

host

my $host = $error->host;

Return the applicable host when one was part of the failing operation.

port

my $port = $error->port;

Return the applicable port.

path

my $path = $error->path;

Return an applicable Unix-domain socket path.

family

my $family = $error->family;

Return applicable socket-family context.

These fields are optional.

An application should test whether a value is defined before using it.

CONNECTION ATTEMPTS

attempts

my $count = $error->attempts;

Outbound Stream connection logic may try several candidate addresses.

attempts records how many connection attempts were made when that information is available.

For example:

on_error => sub ($self, $error) {
    if ($error->type eq 'connect') {
        say "attempts: " . ($error->attempts // 0);
    }
}

For unrelated errors, attempts is undefined.

RESOLVER DETAILS

resolver_message

my $message = $error->resolver_message;

When hostname resolution fails, this field preserves the resolver-specific diagnostic when one is available.

For example, a connection error can retain both the general Linux::Event message and the resolver's own explanation.

For errors unrelated to hostname resolution, this field is undefined.

OUTPUT LIMIT DETAILS

Ordered-byte resources and Process stdin can report hard queue limits using output_limit errors.

pending_bytes

my $bytes = $error->pending_bytes;

Return the amount of queued output that would have existed when the limit was exceeded.

For example:

if ($error->type eq 'output_limit') {
    say "pending: " . $error->pending_bytes;
    say "limit:   " . $error->limit;
}

limit

my $limit = $error->limit;

Return the configured hard limit relevant to the error.

limit is also used with some Datagram size or queue errors.

DATAGRAM QUEUE DETAILS

Datagram output limits may include both byte and packet counts.

pending_datagrams

my $count = $error->pending_datagrams;

Return the number of datagrams that would be pending when a Datagram queue limit is exceeded.

pending_bytes

The same error may also include the pending byte count.

For example:

on_error => sub ($self, $error) {
    if ($error->type eq 'output_limit') {
        say "queued datagrams: " . $error->pending_datagrams;
        say "queued bytes:     " . $error->pending_bytes;
    }
}

These values are undefined when they do not apply.

OVERSIZED DATAGRAM DETAILS

datagram_size

my $size = $error->datagram_size;

A received Datagram that exceeds the configured maximum may produce a datagram_size error.

datagram_size reports the original packet size when Linux made that information available.

limit identifies the configured maximum.

For example:

on_error => sub ($self, $error) {
    if ($error->type eq 'datagram_size') {
        say "packet size: " . $error->datagram_size;
        say "maximum:     " . $error->limit;
    }
}

Linux::Event does not deliver a truncated packet as though it were complete.

TIMEOUT DETAILS

Timeout errors use:

type => 'timeout'

timeout

my $seconds = $error->timeout;

For relative inactivity policies, timeout contains the configured duration in seconds.

Examples include established Stream:

idle_timeout
read_timeout
write_timeout

For an explicitly absolute deadline, timeout may be undefined.

deadline

my $deadline = $error->deadline;

Return the absolute monotonic deadline that expired when that information is available.

The value uses the same monotonic time model as Linux::Event::Kernel::Timer.

For unrelated errors, timeout and deadline are undefined.

FATALITY

fatal

if ($error->fatal) {
    ...
}

Return true when the producer of the Error marked the failure as fatal to the resource or setup operation.

For example, Listener and Datagram setup failures can be marked fatal because the resource cannot continue using the failed configuration.

Not every runtime error is fatal.

For example, a Listener callback failure may be reported without making the Listener itself unusable.

fatal should therefore be treated as explicit context supplied by the resource that created the Error, not inferred solely from type.

AS_STRING

as_string

my $text = $error->as_string;

Return the same concise diagnostic used by string overloading.

The format is approximately:

operation: message (errno=N)

with the operation or errno portion omitted when that field is unavailable.

For example:

my $error = Linux::Event::Error->new(
    type      => 'connect',
    operation => 'connect',
    errno     => 111,
    message   => 'Connection refused',
);

say $error->as_string;

prints:

connect: Connection refused (errno=111)

CONSTRUCTING AN ERROR

Applications may construct compatible Error values directly:

my $error = Linux::Event::Error->new(
    type      => 'application',
    operation => 'decode',
    message   => 'invalid application record',
);

The constructor accepts the same fields exposed by the public accessors.

Fields not supplied remain undefined, except:

type

Defaults to event.

message

Defaults to Linux::Event error.

fatal

Defaults to false.

This can be useful when application-level components want to use the same error shape as Linux::Event.

IMMUTABILITY

Error objects have no public setters.

They are intended to describe a failure that has already occurred.

Application code may keep an Error object, log it, inspect it, or pass it to another layer without expecting its contents to change.

DO NOT ASSUME EVERY FIELD EXISTS

Linux::Event::Error is deliberately one common structured error type.

Different failures populate different context fields.

For example:

connect error
    host
    port
    attempts

timeout error
    timeout
    deadline

output limit
    pending_bytes
    limit

datagram size
    datagram_size
    limit

An accessor that does not apply normally returns undef.

Code should therefore test optional fields rather than assuming they are always present.

SEE ALSO

Linux::Event, Linux::Event::IO::Sock::Stream, Linux::Event::IO::Sock::Listener, Linux::Event::IO::Sock::Dgram, Linux::Event::Kernel::Process, Linux::Event::Kernel::Timer.