Skip to content

Networking: Let a server RPC handler choose its thread - #413

Closed
Segfaultd wants to merge 1 commit into
developfrom
feat/rpc-handler-thread
Closed

Segfaultd wants to merge 1 commit into
developfrom
feat/rpc-handler-thread

Conversation

@Segfaultd

@Segfaultd Segfaultd commented Nov 15, 2026 •

Copy link
Copy Markdown
Member

What

NetworkServer::RegisterRPC takes a HandlerThread: Packet (the default, unchanged), Tick or Script.

net->RegisterRPC<ShopBuy>([this](const ShopBuy &msg, Sender sender, World &world) {
    _shop.Buy(sender.Avatar(), msg.item); // _shop is the tick's, as in PostUpdate
}, Framework::Networking::HandlerThread::Tick);
  • The payload is decoded on the packet thread (a payload cut short is still dropped there), then the handler is posted to the tick's completions or the script thread's tasks.
  • Handlers posted to one thread run in the order their packets arrived.
  • The handler gets the same Sender and World. Reply, Drop and Avatar still work; Avatar() is 0 if the connection closed in between.
  • A posted handler that throws is logged as on the packet thread. It is not timed against slow-packet-handler-ms.
  • Instance sets both posters before PostInit. A bare NetworkServer calls SetHandlerPoster. Registering for a thread with no poster logs critical and aborts, like the other misuse checks.

Why

Since 42, a handler that touches a mod's own state (a service's maps) races with PostUpdate and scripts unless the mod registers that state with the world or guards it. Porting a server mod, every service-touching handler ended up wrapped in the same project-side helper that posts to the tick. This is FiveM's arrangement: a packet's work is handed to the thread that owns what it changes (gscomms_execute_callback_on_main_thread / _on_sync_thread). Built in, mods keep plain service members and say where each handler runs.

No wire, scripting or ABI-breaking change. The existing RegisterRPC calls compile unchanged.

Tests

Two new cases in server_packet_thread:

  • A Tick handler runs on the tick thread, 50 of them in order, each finding the sender's avatar and replying.
  • A Script handler runs on the script thread, which is neither the tick thread nor the packet thread.

Local Windows run: server_packet_thread 21/21 passed. server,packet,network,world,task_scheduler modules: 169/169 passed. Not formatted with clang-format locally (not installed here).

Docs: server_threading.md ("Running a handler on the tick or the script thread") and migrating_to_the_packet_thread.md section 3.

Summary by CodeRabbit

  • New Features
    • RPC handlers can now run on the tick or script thread, while packet-thread execution remains the default. Handlers queued for these threads run in packet-arrival order.
  • Documentation
    • Added guidance on selecting handler threads and accessing tick-owned state safely.

RegisterRPC takes a HandlerThread: Packet (the default, as before),
Tick or Script. A Tick or Script handler is decoded on the packet
thread and posted to the thread that owns the mod state it changes,
in arrival order, with the same Sender and World. A mod's services
keep plain members instead of each mod writing its own hop to the
tick.

The Instance sets where both go before PostInit; a NetworkServer
used alone calls SetHandlerPoster, and registering for a thread with
no poster aborts. Documented in server_threading.md and the packet
thread migration guide.
@coderabbitai

coderabbitai Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

Explain Change →

Caution

Review failed

The pull request is closed.

Walkthrough

RPC handlers can now run on the packet, tick, or script thread. The server decodes posted handlers on the packet thread, then sends them to configured tick or script posters. Tests and documentation cover the routing behavior.

Changes

RPC handler thread routing

Layer / File(s) Summary
Handler thread selection and dispatch
code/framework/src/networking/network_server.h, code/framework/src/networking/network_server.cpp, code/framework/src/integrations/server/instance.cpp, docs/server_threading.md
RegisterRPC accepts a handler thread, with packet execution as the default. Tick and script handlers are decoded on the packet thread and posted to configured threads. The server logs exceptions from posted handlers. Instance::Init configures the tick and script posters.
Routing validation and usage guidance
code/tests/modules/server_packet_thread_ut.h, docs/migrating_to_the_packet_thread.md, docs/server_threading.md
Tests check tick-thread ordering, avatar access, replies, and script-thread execution. The guides describe tick-thread registration for handlers that access state shared with PostUpdate and scripts.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant NetworkServer
  participant SchedulerOwner
  participant ScriptThread
  NetworkServer->>SchedulerOwner: Post tick handler with decoded payload, sender, and world
  NetworkServer->>ScriptThread: Post script handler with decoded payload, sender, and world
Loading

Suggested reviewers: zpl-zak, kheartz

Merge Risk: Moderate · up to dad19

RPC handlers can now choose the packet, tick, or script thread. Shutdown still has gaps: queued script handlers can run after mods release their state, and a handler that triggers shutdown can hang or crash the server. Address these shutdown paths before merging, or explicitly accept them.

- [ ] Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

I’m a rabbit with a message to send,
To the tick thread, then round the bend.
The script thread gets its turn,
While ordered notes return.
I nibble, hop, and test again,
Then tuck my carrots in the den.

@Segfaultd
Segfaultd marked this pull request as ready for review November 16, 2026 08:56
@Segfaultd

Copy link
Copy Markdown
Member Author

Closing: this adds a second way to do what the Framework already prescribes. Handlers stay on the packet thread and mod state is registered with the world (World::RegisterState). The mod that motivated this should register its state instead of hopping to the tick.

@Segfaultd Segfaultd closed this Nov 16, 2026
@Segfaultd
Segfaultd deleted the feat/rpc-handler-thread branch November 16, 2026 08:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

1 participant