Skip to content

⚡ Bolt: optimize PacketType.classify fast path #70

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
igorls wants to merge 1 commit into from
Closed

⚡ Bolt: optimize PacketType.classify fast path #70

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .jules/bolt.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
## YYYY-MM-DD - [PacketType.classify Optimization]
Copy link

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This journal entry still has the YYYY-MM-DD placeholder in the header. Please replace it with the actual date (consistent with .jules/scribe.md / .jules/sentinel.md) so the log stays chronologically useful.

Suggested change
## YYYY-MM-DD - [PacketType.classify Optimization]
## 2026-03-09 - [PacketType.classify Optimization]

Copilot uses AI. Check for mistakes.
**Learning:** `PacketType.classify` is a small, frequently called utility function on the hot path (packet classification). In Zig, marking such functions with `inline` ensures the compiler eliminates function call overhead across module boundaries. Also, standard `switch` statements on integers compile to jump tables. Extracting the dominant case (data-plane packets, type 4) into an explicit `if` branch before the `switch` improves branch prediction and avoids jump table overhead.
Copy link

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The entry states that switch statements “compile to jump tables” and that inline “ensures” cross-module call overhead elimination; those are codegen/optimizer behaviors that can vary by target and optimization level. Suggest softening these claims (e.g., “may”/“often”) so the journal doesn’t encode guarantees that Zig doesn’t promise.

Suggested change
**Learning:** `PacketType.classify` is a small, frequently called utility function on the hot path (packet classification). In Zig, marking such functions with `inline` ensures the compiler eliminates function call overhead across module boundaries. Also, standard `switch` statements on integers compile to jump tables. Extracting the dominant case (data-plane packets, type 4) into an explicit `if` branch before the `switch` improves branch prediction and avoids jump table overhead.
**Learning:** `PacketType.classify` is a small, frequently called utility function on the hot path (packet classification). In Zig, marking such functions with `inline` can help the compiler eliminate function call overhead, even across module boundaries. Also, standard `switch` statements on integers may compile to jump tables. Extracting the dominant case (data-plane packets, type 4) into an explicit `if` branch before the `switch` can improve branch prediction and reduce potential jump table overhead.

Copilot uses AI. Check for mistakes.
**Action:** I will add the `inline` keyword to `PacketType.classify` and add an explicit fast-path `if` check for `wg_transport` (type 4) before the `switch` statement in `src/wireguard/device.zig`. I will also add the `/// Optimization:` comment.
8 changes: 6 additions & 2 deletions src/wireguard/device.zig
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,16 +24,20 @@ pub const PacketType = enum {
stun, // STUN binding response
unknown,

pub fn classify(data: []const u8) PacketType {
/// Optimization: inline function and extract dominant case (data-plane packets) into an explicit fast-path to improve branch prediction and avoid jump table overhead.
pub inline fn classify(data: []const u8) PacketType {
Comment on lines +27 to +28
Copy link

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

pub inline fn forces inlining in all build modes (not just ReleaseFast) and can increase code size/slow debug builds; it’s also the only inline fn under src/ currently. If the goal is ReleaseFast performance, consider keeping this as pub fn and relying on the optimizer unless there’s profiling evidence that forced inlining is required.

Suggested change
/// Optimization: inline function and extract dominant case (data-plane packets) into an explicit fast-path to improve branch prediction and avoid jump table overhead.
pub inline fn classify(data: []const u8) PacketType {
/// Optimization: extract dominant case (data-plane packets) into an explicit fast-path to improve branch prediction and avoid jump table overhead.
pub fn classify(data: []const u8) PacketType {

Copilot uses AI. Check for mistakes.
if (data.len < 4) return .unknown;

// WireGuard messages: first byte is type, next 3 are zeros
const msg_type = std.mem.readInt(u32, data[0..4], .little);

// Fast path for transport data (most common)
if (msg_type == 4) return .wg_transport;

return switch (msg_type) {
Comment on lines +27 to 37
Copy link

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new doc comment asserts the switch has “jump table overhead”, but Zig/LLVM codegen isn’t guaranteed to lower this particular switch to a jump table (it may compile to compares/branches depending on optimization level/target). Suggest rewording to avoid relying on specific codegen details, and focus on the intent (dominant-case fast path) instead.

Copilot uses AI. Check for mistakes.
1 => .wg_handshake_init,
2 => .wg_handshake_resp,
3 => .wg_cookie,
4 => .wg_transport,
else => blk: {
// STUN: check for magic cookie at bytes 4-7
if (data.len >= 8) {
Expand Down