Merge pull request #49 from ausimian/docs-async-worker

Refresh concurrency docs for async NIF dispatch

Author: ausimian

CHANGELOG.md

@@ -53,9 +53,12 @@ Initial release. See the git history for per-milestone detail.
   Qwen3-0.6B (dense and quantized), ViT-base, and Whisper-tiny,
   pinned against HuggingFace reference values.
 - **Worker-thread dispatch.** Each MLX stream is owned by a
-  dedicated OS thread; NIFs hand work to the worker via a
-  promise/future, keeping per-thread Metal `CommandEncoder` state
-  consistent across BEAM scheduler migration.
+  dedicated OS thread. NIFs enqueue work on the worker and return
+  immediately; the worker posts the result back to the caller via
+  `enif_send`, and the public wrapper awaits it with `receive`. No
+  BEAM scheduler (regular or dirty) blocks on MLX work, and the
+  per-thread Metal `CommandEncoder` state stays consistent regardless
+  of how the BEAM migrates Elixir processes between schedulers.
 - **Vendored MLX build.** MLX is built from source via cmake from
   `vendor/mlx` (git submodule); no prebuilt download. Build cache
   keyed on the submodule SHA under `~/Library/Caches/emily/`.

README.md

@@ -206,11 +206,17 @@ and direct MLX round-trips, but most users should go through Nx.
 
 MLX dispatches GPU work through Metal command queues. Emily owns one
 worker thread per command queue; each worker is a dedicated OS thread
-that runs the MLX ops on behalf of BEAM schedulers. NIFs hand their
-work to a worker via a `run_sync` promise (blocks the caller for
-~1–10 µs) rather than executing on the scheduler thread directly,
-which keeps MLX's per-thread `CommandEncoder` consistent and lets
-the BEAM migrate Elixir processes freely.
+that runs the MLX ops on behalf of BEAM processes. NIFs return
+immediately after enqueueing their work on a worker: the worker runs
+the op, then posts `{ref, {:ok, result}}` back to the caller via
+`enif_send`, and the caller's public wrapper awaits that message with
+a plain `receive`. No BEAM scheduler (regular or dirty) blocks on MLX
+work — callers see the same synchronous semantics as before, but the
+scheduler is free to run other processes while the GPU is busy.
+
+Because the MLX stream is pinned to its worker thread, MLX's
+per-thread `CommandEncoder` state stays consistent regardless of how
+the BEAM migrates Elixir processes between schedulers.
 
 By default, every op uses the **default worker** owned by the
 `Emily.MlxStream.Default` GenServer under the application supervisor.