/ 
Hypersonic-0.11
/ 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.

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

# Accept and handle connections
my $client_fd = Hypersonic::Socket::http_accept($listen_fd);
my $req = Hypersonic::Socket::http_recv($client_fd);
Hypersonic::Socket::http_send($client_fd, 'Hello', 'text/plain');
Hypersonic::Socket::close_fd($client_fd);

DESCRIPTION

Hypersonic::Socket provides JIT-compiled XS socket functions for the Hypersonic HTTP server. It handles low-level socket operations while event loop functionality is provided by Hypersonic::Event backend modules.

This module is for internal use by Hypersonic. You typically don't need to use it directly.

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.

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.

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

  • 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:

  • Extending Hypersonic with custom protocols

  • Testing or debugging socket operations

SEE ALSO

Hypersonic - Main HTTP server module

Hypersonic::Event - Event backend selection

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.