/ 
Linux-Event-0.009
/ Linux::Event::Wakeup

NAME

Linux::Event::Wakeup - eventfd-backed wakeups for Linux::Event

SYNOPSIS

use v5.36;
use Linux::Event;

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

# Create once during initialization:
my $waker = $loop->waker;

# From another thread (or a forked child), wake the loop:
$waker->signal;

DESCRIPTION

This module provides a minimal, Linux-native wakeup primitive for Linux::Event based on eventfd(2). It is intended to be used as a building block for thread and process integration without adding policy to the core loop.

The wakeup is implemented internally using eventfd(2) and exposed to the loop as a readable filehandle.

When created via $loop->waker, the loop installs an internal watcher that drains the wakeup fd automatically. This guarantees that $waker->signal (and $loop->stop after waker creation) can reliably wake a blocking backend wait.

The wakeup fd is reserved for loop wakeups and must not be watched directly by user code.

SEMANTICS

The semantics contract for the single-waker model is:

  • Exactly one waker per loop (cached by $loop->waker).

  • Created lazily on first use; never destroyed during loop lifetime.

  • The loop installs an internal read watcher that drains the wakeup fd.

  • User code must not call $loop->watch($waker->fh, ...), as this would replace the loop's internal watcher and break wakeup semantics.

  • signal() is safe from any thread.

  • drain() is non-blocking and returns the coalesced count.

METHODS

fh

my $fh = $waker->fh;

Returns the readable filehandle for this eventfd.

signal

$waker->signal;      # increment by 1
$waker->signal($n);  # increment by $n

Increments the eventfd counter. Multiple signals coalesce in the kernel.

drain

my $count = $waker->drain;

Drains the eventfd counter (non-blocking) and returns the total number of signals coalesced since the last drain.

DEPENDENCIES

Wakeup support requires Linux::FD::Event (part of the Linux::FD distribution). The dependency is loaded lazily so you can still use the core loop features (timers and I/O watchers) without it.

AUTHOR

Joshua S. Day

LICENSE

Same terms as Perl itself.

VERSION

This document describes Linux::Event::Wakeup version 0.007.