Threading Contract

Threading Contract

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

1. The SDK never spawns OS threads. Every public method executes on the OS thread that invoked it.
2. Concurrent invocation of any public method on the same SDK handle is the caller's responsibility to prevent. If two threads enter the SDK on the same handle without external synchronization, behavior is undefined.
3. Sequential calls to public methods on the same handle from different OS threads are supported. The SDK does not pin handles, contexts, or callbacks to a specific thread.
4. Go binding addendum: goroutine migration between OS threads during a single SDK call is supported. Callbacks that the SDK invokes back into Go may run on a different OS thread than the goroutine that initiated the call. Callers must not rely on thread-local OS state inside callbacks.
5. 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.