/ 
Linux-Event-0.002_001
/ Linux::Event::Watcher

NAME

Linux::Event::Watcher - Mutable filehandle watcher handle for Linux::Event::Loop

SYNOPSIS

use v5.36;
use Linux::Event;

my $loop = Linux::Event->new;

my $conn = My::Conn->new(...);

my $w = $loop->watch_fh($fh,
  read => sub ($loop, $fh, $w) {
    my $conn = $w->data;
    $conn->on_read($loop, $fh);
    $w->enable_write if $conn->has_pending_output;
  },
  write => sub ($loop, $fh, $w) {
    my $conn = $w->data;
    $conn->on_write($loop, $fh);
    $w->disable_write if !$conn->has_pending_output;
  },
  data => $conn,
);

$loop->run;

DESCRIPTION

A watcher is a lightweight, mutable handle returned by "watch_fh" in Linux::Event::Loop. It holds:

  • The watched filehandle and its file descriptor

  • User data (data) to avoid closure captures

  • Read/write handlers (mutable)

  • Enable/disable toggles (especially useful for write backpressure)

  • Advanced flags like edge_triggered and oneshot

The watcher itself does not own policy and does not talk directly to the backend. It delegates updates and cancellation to its owning loop.

STATUS

EXPERIMENTAL / WORK IN PROGRESS

This API is a developer release and may change without notice.

METHODS

new(%args)

Constructor used internally by Linux::Event::Loop. Not typically called by users.

loop

Returns the owning loop.

fh

Returns the watched filehandle.

fd

Returns the cached integer file descriptor.

is_active

True if the watcher is still registered.

data

my $x = $w->data;
$w->data($x);

Get or set the user data associated with this watcher.

on_read

$w->on_read(sub ($loop, $fh, $w) { ... });
$w->on_read(undef);

Set or clear the read handler. Clearing disables read notifications.

on_write

$w->on_write(sub ($loop, $fh, $w) { ... });
$w->on_write(undef);

Set or clear the write handler. Clearing disables write notifications.

enable_read / disable_read

Enable or disable read notifications for this watcher.

enable_write / disable_write

Enable or disable write notifications for this watcher.

read_enabled / write_enabled

Return the current enabled state for read/write.

edge_triggered

$w->edge_triggered(1);  # enable edge-triggered mode
$w->edge_triggered(0);  # level-triggered (default)

Advanced: toggles edge-triggered readiness notifications.

oneshot

$w->oneshot(1);         # enable one-shot mode
$w->oneshot(0);

Advanced: toggles one-shot readiness notifications.

cancel

$w->cancel;

Cancel/unregister this watcher. Idempotent.

SEE ALSO

Linux::Event, Linux::Event::Loop, Linux::Event::Backend::Epoll