Design thread-safe APIs

I'm delivering a public API for concurrent use: expose a small set of functions that let callers create, join, and cancel tasks without data races. Require the caller to pass a const reference for read-only data and a unique_ptr for ownership transfer. Validate arguments and document which functions lock which internal mutex. Sign the header and implementation, run the unit tests that spawn 100 threads, and fix any race failures before code review on Thursday.

Before I publish this API to the team, make it obvious which calls are safe from any thread and which must be called from a single thread. Put the thread-safety guarantees at the top of the header, move ownership-transfer signatures up front, show the locking hierarchy in a small diagram, and flag any functions that may block for more than 50 ms. Also suggest a minimal example that demonstrates safe concurrent use for the common case.

I merged the API change; reviewers are saying the design looks clean but CI shows intermittent data races in integration tests that spawn 200 tasks. I cannot reproduce locally and I don't know which call sites are breaking the locking rules. I'm afraid we'll ship an API that causes subtle corruption. What are the most likely causes, what targeted diagnostics should I add to find the culprit, and what's the safest short-term rollback or mitigation so the branch can be stabilized?

Over the last six months we keep landing 'small' API tweaks that later cause concurrency bugs and long debug cycles. We lose time arguing about ownership and locking at review. Which habits should I instill to stop this pattern: how to structure headers, what review checklist items catch the common mistakes, and a lightweight testing practice that prevents these regressions without doubling review time?