Threading Contract

Threading Contract

This page is the canonical threading contract for OpenPit SDK handles across language bindings.

The SDK never spawns OS threads. Every public method executes on the OS thread that invoked it.

The engine handle's threading capability follows from the chosen sync policy:

• Full sync - concurrent invocation on the same handle is safe; sequential cross-thread invocation is also safe.
• Local sync - the handle stays on the OS thread that created the engine.
• Account sync - concurrent invocation on the same handle from multiple threads is safe iff the caller guarantees that calls for the same account are never concurrent (sharded workers, one channel per account hash, or any equivalent pinning scheme). Without that guarantee, concurrent invocation is undefined behavior. Sequential cross-thread invocation is always safe.

Runtime migration of the caller between OS threads during one SDK call is supported (e.g. a goroutine moving across worker threads, or a coroutine resuming on a different thread than it suspended on). Callbacks invoked by the SDK back into host code may run on a different OS thread than the caller that initiated the call, so callback code must not rely on thread-local OS state.

Reject.user_data / Order.user_data / ExecutionReport.user_data / AccountAdjustment.user_data are opaque caller tokens. The SDK never inspects, dereferences, or frees them. Their lifetime, thread-safety, and meaning are entirely the caller's responsibility.

For custom policies that maintain internal state across calls under this contract, see Storage - the built-in synchronization-aware key-value abstraction. It absorbs the memory-synchronization burden so custom policies do not need any external locking around their internal state.