Concurrency Safety rules

Blocking async methods with `.Result` or `.Wait()` can cause deadlocks and prevent efficient asynchronous execution. Use `await` instead for proper async behavior.

Ensure that `wait()` is not called while holding multiple locks to prevent deadlocks.

Identify global variables that are mutable (e.g., lists, dictionaries). Global mutable state can cause unpredictable behavior. Recommend using local variables or encapsulating state in a class.

Await Tasks instead of blocking (no .Result or .Wait()); prefer async/await end-to-end and configure awaits appropriately.

Every goroutine you start should be managed. Avoid launching "fire-and-forget" goroutines that run indefinitely or without any synchronization. Provide a way to stop goroutines (using a cancel context or done channel) and/or track them (e.g., with sync.WaitGroup) to prevent leaks.

Launch goroutines outside of waits, capture loop variables, and use sync.WaitGroup (and buffered channels when needed) to achieve true concurrency.

Mark tests that don't mutate shared state with t.Parallel() and use t.TempDir() for filesystem isolation; avoid package-level globals.

Attach exceptionally/handle to CompletableFuture chains; never assume success.

Prefer thenCompose/thenCombine over blocking get/join; propagate async results end-to-end.

When using a WaitGroup to synchronize goroutines, call Add() before launching each goroutine and ensure each goroutine calls Done() exactly once. Finally, call Wait() to block until all goroutines have called Done(). Misordering Add/Done or mismatched calls will cause issues.

Run blocking I/O and CPU-intensive work inside withContext(Dispatchers.IO) or Dispatchers.Default respectively. Never block the main thread.

Do not use global (package-level) variables for mutable state whenever possible. Instead, encapsulate state in structs or pass it as parameters. If you must use a global variable (for configuration or caching), protect it with mutexes if concurrent access is possible and document its usage.

Memoize expensive results (regex, serializers, tokens) and refresh on expiry using a thread-safe cache.

Encapsulate coroutine parallelization (map async/awaitAll, limited concurrency) into utilities.

By default, use unbuffered channels or a buffer size of one. Only use larger buffers when necessary and carefully considered. Unbuffered channels (size 0) or a size of 1 are the most common; a large buffer can hide synchronization issues or lead to memory bloat if misused.

Protect one-time initializations with Mutex or atomic operations (computeIfAbsent/compareAndSet).

Functions that perform external calls or long operations should accept a `context.Context` parameter and respect its cancellation. Use context timeouts or cancellation signals to stop work that is no longer needed.