Skip to content

refactor(pool): admit tasks at the connection pool - #7

Merged
yfcyrus merged 9 commits into
mainfrom
refactor/pool-admission
Nov 13, 2026
Merged

yfcyrus merged 9 commits into
mainfrom
refactor/pool-admission

Conversation

@yfcyrus

@yfcyrus yfcyrus commented Nov 13, 2026

Copy link
Copy Markdown
Collaborator

refactor: admit tasks at the connection pool

Why

Every work task waited in two queues. First, Promise::async put it on Nitro's shared thread pool, which has at most 10 threads, starts with 3, and adds a thread only when a task is already waiting. Then the operator asked the connection pool for a slot, where interactive requests go first.

Under bulk work, such as thousands of duplicateItem calls, the first queue filled up. A getPathInfo or listDirectory waited behind them before it ever reached the pool's interactive-first queue. Each task also used two threads: a Nitro thread blocked in fut.wait(), and a detached thread that did the work.

What

  • The pool queue is the only place a work task waits. Starting a task never blocks the calling thread, and work tasks no longer use Nitro's thread pool.
  • A queued task holds no thread. A thread starts only once a slot is granted.
  • Each task is granted one slot before its operator runs, and keeps it until the operator returns.
  • No JS API change. Queued tasks now report Pending instead of Idle.
Before After
Where a work task waits Nitro thread pool, then the pool queue pool queue only
Threads per queued task 1 blocked Nitro thread none
Threads per running task 2 (blocked Nitro thread + operator thread) 1
Max running work threads 10 (Nitro limit, shared app-wide) 1 per slot (4)
Interactive op under bulk load waits behind bulk in the Nitro queue assigned on slot 0 once it frees
Lifecycle ops serial thread, blocked while a detached thread runs serial thread, run inline

Design

JS call → prepare()              validate arguments, record paths (no SMB)
        → requestContext(mode)   queue; status Pending
        → slot reserved          start one thread for the task
        → activate()             connect the slot if needed, on that thread
        → run()                  status Running; slot released when it returns
  • requestContext is asynchronous. It queues ContextCallbacks (onGranted, onRejected) and returns at once. Exactly one callback runs per request, outside the pool mutex.
  • SlotReservation: a move-only handle to a slot marked Activating. activate() connects the slot if needed (TCP, negotiate, session setup, tree connect) on the task's own thread. Before, this ran inside tryAssignNext on whichever thread called it, which could be a thread that was releasing a slot. With the new asynchronous flow it would have been the JS thread. Dropping a reservation without activating it frees the slot.
  • Operators declare their slot type. acquireMode() returns Interactive, Metadata, or nullopt for lifecycle operators. listDirectory picks based on maxDepth. Operators use context() and can no longer request a slot themselves, which also removes the possibility of a task waiting on itself for a second slot.
  • prepare(): argument checks and setSourceDestination run before the task queues. Queued transfers still show their paths, and invalid arguments fail without taking a place in the queue.
  • Cancel and drain: queued requests are removed and rejected without starting a thread. Requests whose slot is activating are flagged and fail with Cancelled once activation returns.
  • Lifecycle: initialize, connect, connectShare, and disconnect take no slot. They run inline on the lifecycle thread.

Related cleanups

  • listShares is a normal Interactive request. It was the only request that could not open a new slot; with every slot busy it sat at the head of the queue and blocked requests behind it that could have opened one.
  • deleteItem keeps one Metadata slot for stat, unlink, and tree delete. Before, it released the slot and queued again between phases.
  • SmbTask runs a single operator. The unused spawn(), multi-operator bookkeeping, and per-operator progress are removed.
  • Removed MetadataContextLease. copyTreeImpl takes the caller's handle and no longer acquires its own slot when none is passed.
  • publishResult now writes under stateMutex_, which matches how publishedResult reads it.

Notes for reviewers

  • Commit 7 (perf(pool): admit work at the pool…) is the core change. Commits 1–6 prepare for it and each builds on its own.
  • requestContext may run onRejected synchronously when the pool is not running. In that case a task can settle before startTask returns, the same final state as before but no longer delayed by a hop to a Nitro thread.
  • destroy() still uses Promise::async. No task holds a Nitro thread anymore, so it no longer waits behind running tasks.

SmbTask kept a list of operators, a pending counter, and per-op progress
for spawn(), which no operator calls. Each task also started a detached
thread while the thread that launched it blocked in start(). Run the
single operator inline on the thread that starts the task.

- remove spawn, launchOp, appendOps, pending_, and OperatorContext::opIndex
- track one progress entry; onOpStatus/onOpProgress drop the op index
- run() replaces start() and calls the operator instead of waiting on a
  completion future
publishResult wrote resultValue_ without stateMutex_ while
publishedResult read it under the lock, so a JS read could race the
operator thread.

- take stateMutex_ in publishResult
MetadataContextLease only wrapped a PoolContextHandle, and copyTreeImpl
acquired its own lease when a caller passed none. A caller that already
held a slot could then wait on itself once the pool was full. Take the
caller's handle instead.

- delete MetadataContextLease.hpp and OperatorBase::makeMetadataLease
- copyTreeImpl and inspectCopyTreeSource take a required PoolContextHandle&
- copy and duplicate request a Metadata context directly
Delete gave up its slot after stat and again before unlink or the tree
delete, so each phase queued behind other work for a new slot. Keep the
first slot for the whole delete.

- stat, unlink, and the listed tree delete share one context
listShares was the only request that could not add a slot. When it
reached the head of the queue with every slot busy, tryAssignNext
stopped there, and growable requests behind it waited even though the
pool could open another slot. The operator now requests a context like
any other Interactive operation.

- ListSharesOperator enumerates through the granted handle's manager
- remove SmbConnectionPool::listShares and canGrowPoolSlot
Each operator called requestContext inside run(), so its mode was only
known once the operator was already running. Operators now declare their
mode, and the task acquires the slot before run() and hands it over
through context(). Argument checks and task paths move to prepare(), so
they still happen before the task waits for a slot.

- add acquireMode(); nullopt marks lifecycle operators
- listDirectory picks Interactive or Metadata from maxDepth
- add prepare() for validation and setSourceDestination, without SMB I/O
- remove OperatorBase::requestContext; operators use context()
Every work task first waited in Nitro's shared Promise::async queue,
which has at most 10 threads and grows lazily, and then kept one of those
threads blocked for its whole run. Under bulk work, interactive requests
waited behind it before they reached the pool's interactive-first queue.
Queue work only at the pool and start a thread once a slot is granted.

- requestContext is asynchronous: it queues ContextCallbacks and returns at once
- SlotReservation is a move-only handle to a reserved slot; activate()
  connects on the runner thread, never on the JS thread or a releasing thread
- callbacks fire outside the pool mutex; cancel, drain, and NotConnected
  reject queued requests without starting a thread
- SmbTask::prepare/run/reject replace the blocking run; lifecycle tasks
  run inline on the lifecycle thread
- remove ExecutionLane and PoolSlot::accepts; startTask routes by acquireMode()
- queued tasks now report Pending instead of Idle
Describe the single admission point, the one-task-one-slot rule, the
thread bounds, and when a task reports Pending.

- add a Task admission section to ARCHITECTURE
- note that every request may open a slot; drop the PoolSlot::accepts snippet
- TASK_MODEL: status is Pending while queued for a slot
Pending/Running need clear labels.

- Active/Waiting badges
- Running before Pending
- In progress / Finished
@yfcyrus
yfcyrus merged commit d9e9aa9 into main Nov 13, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant