NAME
Hypersonic - Blazing fast HTTP server with JIT-compiled C event loop
SYNOPSIS
use Hypersonic;
my $server = Hypersonic->new();
# Handlers return STRINGS - they run ONCE at compile time
$server->get('/api/hello' => sub {
'{"message":"Hello, World!"}'
});
$server->get('/health' => sub {
'OK'
});
# Compile routes - generates C code and compiles via XS::JIT
$server->compile();
# Run the server
$server->run(
port => 8080,
workers => 4,
);DESCRIPTION
Hypersonic is a benchmark-focused micro HTTP server that uses XS::JIT to generate and compile C code at runtime. The entire event loop runs in C with no Perl in the hot path.
What it does:
- 1. Route handlers run ONCE at
compile()time - 2. Response strings (including HTTP headers) are baked into C as static constants
- 3. A pure C event loop (kqueue/epoll) is generated and compiled
- 4. At runtime, the C code handles recv/dispatch/send with zero Perl calls
What it is NOT:
This does NOT use Perl custom ops (like Meow's accessors). It generates XS functions that are called once to enter the C event loop. The speed comes from the pure C event loop, not from op-tree manipulation.
Performance: ~290,000 requests/second on a single core (macOS/kqueue).
METHODS
new
my $server = Hypersonic->new(%options);Create a new Hypersonic server instance.
Options:
- cache_dir
-
Directory for caching compiled XS modules. Default:
_hypersonic_cache
get, post, put, del, patch, head, options
# Static route - handler runs ONCE at compile time
$server->get('/path' => sub { 'response string' });
# Dynamic route - handler runs PER REQUEST
$server->get('/users/:id' => sub {
my ($req) = @_;
my $id = $req->{id};
return qq({"id":"$id"});
});
# Explicit dynamic route
$server->post('/api/data' => sub {
my ($req) = @_;
my $body = $req->{body};
return qq({"received":"$body"});
}, { dynamic => 1 });Register a route handler. The handler must return a string.
Routes with path parameters (:param) are automatically dynamic. Use { dynamic => 1 } to force a route to be dynamic.
Dynamic handlers receive a hashref with: method, path, body, id (if path param).
compile
$server->compile();Compile all registered routes into JIT'd native code. This:
1. Executes each handler once to get the response string 2. Generates C code with the strings as static constants 3. Compiles the C code via XS::JIT
dispatch
my $response = $server->dispatch(['GET', '/api/hello', '', 1, 0]);Dispatch a request and return the response. Request is an arrayref: [method, path, body, keep_alive, fd]
run
$server->run(port => 8080, workers => 4);Start the HTTP server. (Event loop implementation coming in Phase 2)
benchmark
======================================================================
Benchmark: Route matching for GET /api/hello
======================================================================
Benchmark: running Dancer2, HTTP_Router, Hypersonic, Mojolicious, Plack for at least 3 CPU seconds...
Dancer2: 3 wallclock secs ( 3.15 usr + 0.01 sys = 3.16 CPU) @ 17713.29/s (n=55974)
HTTP_Router: 3 wallclock secs ( 3.15 usr + 0.01 sys = 3.16 CPU) @ 107178.48/s (n=338684)
Hypersonic: 2 wallclock secs ( 3.07 usr + 0.00 sys = 3.07 CPU) @ 9336325.08/s (n=28662518)
Mojolicious: 4 wallclock secs ( 3.12 usr + 0.02 sys = 3.14 CPU) @ 196110.19/s (n=615786)
Plack: 4 wallclock secs ( 3.06 usr + 0.02 sys = 3.08 CPU) @ 3937159.09/s (n=12126450)
Comparison (higher is better):
Rate Dancer2 HTTP_Router Mojolicious Plack Hypersonic
Dancer2 17713/s -- -83% -91% -100% -100%
HTTP_Router 107178/s 505% -- -45% -97% -99%
Mojolicious 196110/s 1007% 83% -- -95% -98%
Plack 3937159/s 22127% 3573% 1908% -- -58%
Hypersonic 9336325/s 52608% 8611% 4661% 137% --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.