Performance [P2]: Make entity method signature caching effective

[berndverst]

Summary

_execute_entity_batch() constructed a new _EntityExecutor inside its per-operation loop:

for operation in req.operations:
    start_time = datetime.now(timezone.utc)
    executor = _EntityExecutor(self._registry, self._logger, self._data_converter)

_EntityExecutor memoizes reflected entity method signatures in _entity_method_cache, but
because a fresh executor was built for every operation that cache was always cold — so the
inspect.signature() call that decides whether an entity method takes an input argument was paid
on every single entity operation, and the memoization never did anything.

This PR makes the caching actually effective:

1. One executor per batch. Executor construction is hoisted out of the for operation ...
   loop.
2. A worker-owned, bounded, thread-safe signature cache. A new
   _EntityMethodSignatureCache is created once in TaskHubGrpcWorker.__init__ and passed to
   each batch executor, so a given (entity type, operation) pair is reflected once for the
   lifetime of the worker rather than once per batch or once per operation.

The cache is bounded (1024 entries, oldest evicted first) rather than an unbounded dict, because
entity type objects and operation names come from user code and are unbounded in principle —
an unbounded cache keyed on arbitrary user input would be a memory leak.

Design notes

• The dispatch logic in _EntityExecutor.execute() is untouched. The new cache exposes
  get() and __setitem__, so the two existing call sites work verbatim. Only where the boolean
  is stored changed; how it is computed is byte-identical, including the fact that the signature
  is taken from the bound method (using the class attribute instead would count self as a
  required parameter and invert the dispatch decision).
• Thread safety. Entity work items are processed concurrently on the worker's thread pool.
  Reads are a single dict.get (atomic); every mutation, including eviction, happens under a
  Lock.
• Eviction is FIFO, not LRU, deliberately: it keeps the hot read path lock-free and
  allocation-free, whereas LRU would require a write (pop/reinsert) on every cache hit.

Backwards compatibility

No public API changes. _EntityExecutor's existing three-argument constructor still works — the
shared cache is an optional fourth argument, defaulting to a private per-executor cache — so
existing callers such as tests/durabletask/test_type_discovery.py and
tests/durabletask/scheduled/test_schedule_entity.py are unaffected. No renames, no removed
symbols, no changed import paths. The no-argument vs. input-argument dispatch distinction and all
error messages for unknown or invalid operations are preserved.

No CHANGELOG.md entry: per the repo's contributor instructions this is an internal performance
refactor with no externally observable behavior change.

Tests

Added 17 tests to tests/durabletask/test_entity_executor.py across three classes. They count
reflection precisely by monkeypatching the inspect name inside durabletask.worker with a
counting shim (that module calls inspect.signature in exactly one place — the entity dispatch),
so the counts are unambiguous:

• TestEntityMethodSignatureCaching — an executor reflects once per (type, operation); distinct
  operations and distinct entity types get distinct entries; an explicitly shared cache is honored.
• TestEntityBatchSignatureCaching — a batch of N operations on one entity type reflects once, not
  N times; the cache survives across separate _execute_entity_batch calls; the worker's cache is
  actually populated; and no-arg vs. input-arg dispatch and unknown-operation errors still behave
  identically.
• TestEntityMethodSignatureCacheBounds — eviction at the limit, non-positive max_size clamping,
  and concurrent writers from multiple threads.

These are genuine regression tests: reverting _execute_entity_batch to the pre-fix
executor-per-operation form makes four of them fail (for example
assert 4 == 2 on the signature-call count).

Why the max(1, max_size) clamp is load-bearing

The clamp looks like a defensive nicety, but it is the thing standing between a mis-set bound and a
silent performance regression. With a bound of 0 and no clamp, every entry is evicted
immediately after it is inserted, so every lookup misses and the exact per-operation reflection
this PR removes comes straight back — silently, with no error, while every other test stays green.
The end-to-end test pins this: without the clamp it fails assert 3 == 1 on the reflection count.

A negative bound is a distinct and noisier failure: the eviction loop pops past an already-empty
dict and raises StopIteration.

Both modes are covered, parametrized over 0, -1, and -1024, and both were verified red before
green by temporarily removing the clamp (all five clamp tests fail without it; the four pre-existing
bounds tests still pass, so the new tests are not vacuous).

Verification

All commands run in a session-local venv with both packages installed editable from this worktree,
on the branch after merging main.

• Core unit tests — pytest tests/durabletask -q --ignore-glob="*_e2e.py" → 701 passed, 7 skipped, 0 failed.
• Provider unit tests — pytest tests/durabletask-azuremanaged/test_sandboxes_extension.py tests/durabletask-azuremanaged/test_durabletask_grpc_interceptor.py -q → 45 passed.
• flake8 durabletask/worker.py tests/durabletask/test_entity_executor.py → clean.
• pyright with the repo's own pyrightconfig.json (strict) → 0 diagnostics in durabletask/worker.py.

main was merged in rather than rebased, since the PR is already under review. Its worker.py
changes land entirely in the orchestration path (lazy itertools.chain over history events, the
orchestration-name lookup, and the rewind passes) and do not overlap the entity batch path or
_EntityExecutor, so the net production diff here is unchanged at +62/-3.

Fixes #186

[Copilot]

Pull request overview

This PR improves entity execution performance in the core durabletask worker by ensuring reflected entity-method signature information is actually cached across operations and batches, avoiding repeated inspect.signature() overhead in entity-heavy workloads.

Changes:

• Hoists _EntityExecutor construction out of the per-operation loop so one executor is reused per entity batch.
• Introduces a worker-owned _EntityMethodSignatureCache (bounded + synchronized on writes) and wires it into _EntityExecutor.
• Adds regression tests validating signature reflection counts across repeated operations, batches, and concurrent writers.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
durabletask/worker.py	Reuses a single executor per batch and adds a worker-level bounded cache for entity method signature reflection results.
tests/durabletask/test_entity_executor.py	Adds tests to verify signature caching behavior across executors/batches and validates cache bounds and concurrency behavior.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.