Threading Contract

Threading Contract

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.
• No 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 (a goroutine moving across worker threads, 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, so callback code must not rely on thread-local OS state.

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

Custom policies that need internal state across calls should use Storage - the synchronization-aware key-value abstraction that matches the engine's sync policy automatically and removes the need for external locking around policy state.