/ 
Hypersonic-0.11
/ Hypersonic::Event

NAME

Hypersonic::Event - Event backend registry and selection

SYNOPSIS

use Hypersonic::Event;

# Auto-detect best backend for this platform
my $backend_name = Hypersonic::Event->best_backend;
# Returns: 'kqueue' on macOS, 'epoll' on Linux, etc.

# Get the backend module
my $backend = Hypersonic::Event->backend;           # Auto-detect
my $backend = Hypersonic::Event->backend('epoll');  # Specific

# List available backends on this system
my @available = Hypersonic::Event->available_backends;
# e.g., ('epoll', 'poll', 'select') on Linux

# Register a custom backend
Hypersonic::Event->register_backend('mybackend', 'My::Event::Backend');

DESCRIPTION

Hypersonic::Event is the central registry for event loop backends in Hypersonic. It provides automatic detection of the best available backend for the current platform and lazy-loading of backend modules.

Backend Priority

When auto-detecting, backends are tried in this order:

1. io_uring - Linux 5.1+ with liburing (fastest)
2. epoll - Linux (fast, edge-triggered)
3. kqueue - BSD/macOS (fast)
4. iocp - Windows I/O Completion Ports (fast, completion-based)
5. event_ports - Solaris/illumos (fast, one-shot)
6. poll - POSIX systems (O(n) but portable)
7. select - Universal including Windows (slowest, FD_SETSIZE limit)

CLASS METHODS

best_backend

my $name = Hypersonic::Event->best_backend;

Returns the name of the best available backend for the current platform. Dies if no backend is available.

backend

my $module = Hypersonic::Event->backend;
my $module = Hypersonic::Event->backend($name);

Returns the backend module (class name) for the given backend name. If no name is provided, uses best_backend().

The module is loaded via require if not already loaded. Dies if the backend is unknown or not available on this platform.

available_backends

my @names = Hypersonic::Event->available_backends;

Returns a list of backend names that are available on the current system. Backends are returned in priority order.

all_backends

my @names = Hypersonic::Event->all_backends;

Returns a list of all registered backend names (whether available or not).

register_backend

Hypersonic::Event->register_backend($name, $module);

Register a custom backend. The module must implement the backend interface (see Hypersonic::Event::Epoll for an example).

unregister_backend

Hypersonic::Event->unregister_backend($name);

Remove a backend from the registry.

BACKEND INTERFACE

Each backend module must implement these methods:

  • name() - Return the backend name string

  • available() - Return true if usable on this platform

  • includes() - Return C #include directives

  • defines() - Return C #define directives

  • event_struct() - Return the C struct name for events

  • gen_create($builder, $listen_fd_var) - Generate event loop creation

  • gen_add($builder, $loop_var, $fd_var) - Generate fd add

  • gen_del($builder, $loop_var, $fd_var) - Generate fd remove

  • gen_wait($builder, $loop_var, $events_var, $count_var, $timeout_var) - Generate wait

  • gen_get_fd($builder, $events_var, $index_var, $fd_var) - Generate fd extraction

Optional methods:

  • extra_cflags() - Additional compiler flags

  • extra_ldflags() - Additional linker flags

SEE ALSO

Hypersonic, Hypersonic::Event::Epoll, Hypersonic::Event::Kqueue, Hypersonic::Event::Poll, Hypersonic::Event::Select, Hypersonic::Event::IOUring, Hypersonic::Event::IOCP, Hypersonic::Event::EventPorts

AUTHOR

LNATION <email@lnation.org>

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.