mongodb/docs/baton.md

Server-Internal Baton Pattern

Batons are lightweight job queues in mongod and mongos processes that allow recording the intent to execute a task (e.g., polling on a network socket) and deferring its execution to a later time. Batons, often by reusing Client threads and through the Waitable interface, move the execution of scheduled tasks out of the line, potentially hiding the execution cost from the critical path. A total of four baton classes are available today:

• Baton
• DefaultBaton
• NetworkingBaton
• BatonASIO

Baton Hierarchy

All baton implementations extend Baton. They all expose an interface to allow scheduling tasks on the baton, to demand the awakening of the baton on client socket disconnect, and to create a SubBaton. A SubBaton, for any of the baton types, is essentially a handle to a local object that proxies scheduling requests to its underlying baton until it is detached (e.g., through destruction of its handle).

Additionally, a NetworkingBaton enables consumers of a transport layer to execute I/O themselves, rather than delegating it to other threads. They are special batons that are able to poll network sockets, which is not feasible through other baton types. This is essential for minimizing context switches and improving the readability of stack traces.

DefaultBaton

DefaultBaton is the most basic baton implementation. A default baton is tightly associated with an OperationContext, and its associated Client thread. This baton provides the platform to execute tasks while a client thread awaits an event or a timeout (e.g., via OperationContext::sleepUntil(...)), essentially paving the way towards utilizing idle cycles of client threads for useful work. Tasks can be scheduled on this baton through its associated OperationContext and using OperationContext::getBaton()::schedule(...).

Note that this baton is not available for an OperationContext that belongs to a ServiceContext with a TransportLayerASIO transport layer. In that case, the aforementioned interface will return a handle to BatonASIO.

BatonASIO

This baton is only available for Linux and extends NetworkingBaton to implement a networking reactor. It utilizes poll(2) and eventfd(2) to allow client threads await events without busy polling.

Example

For an example of scheduling a task on the OperationContext baton, see here.

Considerations

Since any task scheduled on a baton is intended for out-of-line execution, it must be non-blocking and preferably short-lived to ensure forward progress.