/ 
Hypersonic-0.03
/ Hypersonic::Socket

NAME

Hypersonic::Socket - JIT-compiled socket operations for Hypersonic

SYNOPSIS

use Hypersonic::Socket;

# Platform detection
my $platform = Hypersonic::Socket::platform();    # 'darwin', 'linux', etc.
my $backend  = Hypersonic::Socket::event_backend();  # 'kqueue' or 'epoll'

# Low-level socket operations (usually called internally)
my $listen_fd = Hypersonic::Socket::create_listen_socket(8080);
my $loop_fd   = Hypersonic::Socket::create_event_loop($listen_fd);

# Event loop (simplified example)
while (1) {
    my $events = Hypersonic::Socket::ev_poll($loop_fd, 1000);
    for my $event (@$events) {
        my ($fd, $flags) = @$event;
        if ($fd == $listen_fd) {
            my $client_fd = Hypersonic::Socket::http_accept($listen_fd);
            Hypersonic::Socket::event_add($loop_fd, $client_fd);
        } else {
            my $req = Hypersonic::Socket::http_recv($fd);
            Hypersonic::Socket::http_send($fd, 'Hello', 'text/plain');
            Hypersonic::Socket::close_fd($fd);
        }
    }
}

DESCRIPTION

Hypersonic::Socket provides JIT-compiled XS socket functions for the Hypersonic HTTP server. It automatically detects the platform and compiles the appropriate event backend (kqueue or epoll).

This module is for internal use by Hypersonic. You typically don't need to use it directly unless building custom event loops.

All functions are compiled to native XS code on first use via XS::JIT::Builder.

PLATFORM DETECTION

platform

my $os = Hypersonic::Socket::platform();

Returns the detected platform:

  • darwin - macOS

  • linux - Linux

  • freebsd - FreeBSD

  • openbsd - OpenBSD

  • netbsd - NetBSD

Dies on unsupported platforms.

event_backend

my $backend = Hypersonic::Socket::event_backend();

Returns the event backend for the current platform:

  • kqueue - macOS, FreeBSD, OpenBSD, NetBSD

  • epoll - Linux

CLASS METHODS

compile_socket_ops

Hypersonic::Socket->compile_socket_ops(
    cache_dir => '_socket_cache',
);

Compile the JIT socket operations. Called automatically on module import.

Options:

cache_dir

Directory for caching compiled XS code. Default: _hypersonic_socket_cache

SOCKET FUNCTIONS

All functions are JIT-compiled to XS for maximum performance.

create_listen_socket

my $fd = Hypersonic::Socket::create_listen_socket($port);

Create a non-blocking TCP listening socket.

Features:

  • SO_REUSEADDR - Allow quick restart

  • SO_REUSEPORT - Enable kernel load balancing (Linux)

  • O_NONBLOCK - Non-blocking I/O

  • Bound to all interfaces (INADDR_ANY)

Returns the file descriptor, or -1 on error.

create_event_loop

my $loop_fd = Hypersonic::Socket::create_event_loop($listen_fd);

Create an event loop (kqueue or epoll) and register the listen socket.

Returns the event loop file descriptor, or -1 on error.

event_add

my $result = Hypersonic::Socket::event_add($loop_fd, $fd);

Add a file descriptor to the event loop for read events.

Returns 0 on success, -1 on error.

event_del

my $result = Hypersonic::Socket::event_del($loop_fd, $fd);

Remove a file descriptor from the event loop.

Returns 0 on success, -1 on error.

ev_poll

my $events = Hypersonic::Socket::ev_poll($loop_fd, $timeout_ms);

Wait for events on the event loop.

Returns an arrayref of [$fd, $flags] pairs, where:

  • $fd - File descriptor with pending events

  • $flags - Event flags (read, write, error)

http_accept

my $client_fd = Hypersonic::Socket::http_accept($listen_fd);

Accept a new connection on the listen socket.

Returns the client file descriptor, or -1 on error.

http_recv

my $request = Hypersonic::Socket::http_recv($fd);

Receive and quick-parse an HTTP request.

Returns an arrayref: [method, path, body, keep_alive, fd]

  • method - HTTP method (GET, POST, etc.)

  • path - Request path

  • body - Request body (for POST, PUT, etc.)

  • keep_alive - 1 if Connection: keep-alive, 0 otherwise

  • fd - Client file descriptor

Uses zero-copy parsing for maximum speed.

http_send

Hypersonic::Socket::http_send($fd, $body, $content_type);

Send an HTTP 200 response with the given body.

Uses writev() for zero-copy I/O when possible.

http_send_404

Hypersonic::Socket::http_send_404($fd);

Send a pre-computed 404 Not Found response.

close_fd

Hypersonic::Socket::close_fd($fd);

Close a file descriptor.

PERFORMANCE

All functions achieve approximately 7M operations/second in benchmarks due to:

  • JIT compilation to native XS

  • Zero-copy parsing

  • Platform-optimized event backends

  • Minimal memory allocations

INTERNAL USE

These functions are typically called by the main Hypersonic module's JIT-compiled event loop. The generated C code calls these functions directly for socket operations.

You only need to use this module directly if:

  • Building custom event loops

  • Extending Hypersonic with custom protocols

  • Testing or debugging socket operations

SEE ALSO

Hypersonic - Main HTTP server module

XS::JIT::Builder - JIT compilation API

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.