Should a shared library call runtime.LockOSThread internally, or push thread pinning onto its callers?

## Why this is a design decision and not a coding one `runtime.LockOSThread` looks local: one call, one goroutine. It is not, for three reasons. **It costs a thread.** While the lock is held, that OS thread serves one goroutine. If the affected state cannot be restored, the correct cleanup is to let the goroutine exit while still locked so the runtime terminates the thread, which means a thread creation and teardown per operation. The resource that scales is threads, not goroutines. **It constrains the caller's code.** Pinning is per goroutine and is never inherited. Any callback you invoke runs on the pinned goroutine, so the caller must not start goroutines inside it, must not park it for long, and must not assume anything it starts sees the thread state. That is a contract, whether or not you write it down. **It cannot be withdrawn.** Once the exported documentation says "call this on a goroutine you have locked", every caller has code shaped around it. In a package other teams import, that sentence is as permanent as a function signature. ## The containment test Ask how far the affinity reaches. - **Contained in one call.** The operation begins and ends inside your function, and no caller code runs while the thread is dirty. Then hide it entirely: create a goroutine, lock it, do the work, return the result over a channel, and let the goroutine die. Callers see a plain function. This is the right default. - **Outliving the call.** You return a handle, a session, or a context whose later use must land on the same thread. Now the affinity spans calls you do not control, and hiding it means owning a long-lived pinned goroutine that serialises every use of the handle: one thread for the process, requests funnelled to it, results sent back. That is a real design with real consequences — serialisation, an owner to shut down, and a queue that can back up — and it should be chosen deliberately. - **Caller code inside the pinned region.** You take a callback that must run on the thread. Then the requirement is unavoidably part of the API and belongs in the doc comment, spelled out: what must happen on the locked goroutine, that the callback must not offload work to other goroutines, and that the caller must not unlock. ## The rule about somebody else's goroutine The lock count belongs to the goroutine, and if your function is called on the caller's goroutine, the count is shared with them. Locking and unlocking symmetrically is safe because the counter nests. Unlocking more than you locked is not: it can silently release pinning the caller established for their own per-thread state, producing a bug in their code with no trace of your package. The discipline is simple — only unlock what you locked, and prefer to lock a goroutine you created. ## The capacity side, which is not yours to decide alone A design that pins one thread per in-flight operation converts request concurrency into process threads. The runtime has a ceiling on live threads — 10000 by default, changeable with `runtime/debug.SetMaxThreads` — and crossing it is not an error you can handle: the runtime prints a line about the program exceeding the thread limit and aborts with a fatal thread-exhaustion error. That means the ceiling is a tripwire, not a capacity knob, and raising it converts a crash into a slower crash plus memory spent on kernel stacks. So two owners appear. The library author owns whether pinning is in the API. Whoever owns the service's capacity owns how many pinned operations may be in flight and what the process thread ceiling should be, and they can legitimately overrule a library design that assumes threads are free. The way to keep that conversation short is to publish the cost: state in the package documentation that each concurrent operation holds an OS thread, so the caller can size a limiter rather than discovering the ceiling in production. ## When the answer is neither If the pinned region would be large, or the state you must set is dangerous to leave on any thread, moving the work to a separate process is often better than either option. Re-execute the binary, set the state in the child before it becomes concurrent, and communicate over a pipe. It costs a process instead of a thread, removes the affinity from your API completely, and makes it impossible for unrelated code in your process to inherit the state. ## What a reviewer should insist on A proposal to add pinning to an exported API should answer four questions: which calls must observe the thread state; whether caller code ever runs inside the pinned region; who terminates the pinned goroutine and when; and how many can be in flight at once. If the design cannot answer the fourth, it is not ready, whatever the code looks like.