한국어 | English
Systems Index | Previous: Architecture | Next: I/O Thread
Core threading model¶
What this chapter defines — The types of threads that Core actually creates, their responsibilities, and the communication structure between them.
1. Threading model overview¶
zlink Core uses several types of threads with distinct roles, centered on Context, the top-level container that holds I/O processing threads and sockets. This document explains those thread types, their responsibilities, and how commands and payloads move between threads. It is intended for developers who maintain Core internals or review thread boundaries.
Most of this chapter describes the implementation. When the implementation changes, update this document to match the code. The following documents own the public contracts that callers depend on; this chapter does not redefine those contracts.
| Related contract | Defining document |
|---|---|
| Public boundaries between threads | Core runtime boundary |
| Thread safety of each socket API | Common socket thread safety |
| Context options such as the number of I/O threads | Context |
2. Thread types¶
The background threads that perform network sends and receives are called I/O threads. Including the application-owned thread, five types of execution threads participate in the Core runtime.
| Thread | Responsibility | Count |
|---|---|---|
| Application thread | Public API calls and blocking waits | Application-owned |
| I/O thread | Transport completions, engine state, and socket command delivery | Context io_threads |
| Reaper thread | Cleanup of terminated sockets and owned objects | One per Context |
| Context control runtime | Internal monitor queue delivery and Auto HWM recalculation | One per started Context (core-ctrl) |
| Timer scheduler | Generic timer deadlines and fire counts | One per process while timers exist |
In the table, an engine is an internal object responsible for transport sends and receives and for protocol encoding and decoding for one connection. I/O thread internals describes the I/O thread event loop, engine processing, and connection assignment criteria.
Core has no service mailbox or MeshNode-specific ingress thread.
3. Cross-thread communication¶
Commands from an application thread are delivered to the owner thread through a mailbox, the channel used to pass commands between threads. Payload data moves between the socket semantic layer and an engine through pipe queues. Each connection is pinned to one I/O thread, and multiple I/O threads do not mutate the same connection's engine state concurrently.
The following paragraph summarizes the contract owned by common socket thread safety. Send, publish, and routed send on supported handle types can be used concurrently from multiple threads. Low-frequency control paths are serialized for correctness. Unless a formal API specifies a different contract, receive is single-consumer: only one consumer thread receives at a time.
4. Pull eventing¶
No application callback is registered for socket monitors or generic timers. The application
receives events and fire counts directly with zlink_socket_monitor_recv() and
zlink_timer_recv(), and can wait for the readiness of both handles together through a poller.