Resources & Locking

Resources, enqueue gates, and distributed locks.

Resources

Method	Description
`resource(...)`	Register an injectable resource.
`resource(name, ResourceDefinition)`	Register a pre-built definition — the escape hatch for knobs the typed overloads don't cover, such as `withReloadable(true)`.
`resourceMetrics()`	Per-resource created/disposed/active counters.
`reloadResources()` / `reloadResources(names)` → `Map<String, Boolean>`	Hot-reload resources: dispose what is cached, rebuild dependency-first. No argument sweeps every `withReloadable(true)` resource; an unknown name reports `false` rather than throwing. Empty when no worker is running — that is where the instances live.

Enqueue gates

Method	Description
`predicate(taskName, Predicate)` / `gate(taskName, EnqueueGate)`	Enqueue-time gates: reject, skip, or defer submissions.
`predicateStats()` → `PredicateStats`	Gate outcome counters: `allowed`, `skipped`, `deferred`, `rejected`, `errors`. One count per gated enqueue.
`intercept(Interceptor)`	Pass / convert / redirect / reject each enqueue before serialization.
`analyzeArguments(taskName, payload)` → `InterceptionAnalysis`	Dry-run the interceptor chain: what it would do, without enqueuing. A chain that would reject comes back as `rejected` instead of throwing.

Distributed locks

Method	Description
`lock(name, ttlMs)` / `lock(name)`	A distributed `Lock`, not yet acquired (default 30s TTL). Each instance mints its own owner id, so two handles on the same name contend rather than share.
`withLock(name, ttlMs, Runnable)` → `boolean`	Acquire → run → release, as try-with-resources. `false` means another owner held the lock and `body` never ran — it is a verdict, not a failure, so nothing is thrown.
`lockInfo(name)` (alias `getLockInfo`) → `Optional<LockInfo>`	The current holder: `lockName`, `ownerId`, `acquiredAt`, `expiresAt` (Unix milliseconds). Empty when the lock is free.

The `Lock` handle

Lock is AutoCloseable and close() releases, so try-with-resources is the normal shape. Acquisition is never implicit — a handle you never acquire() guards nothing.

Method	Description
`acquire()` → `boolean`	Take the lease for this instance's owner id. `false` when another owner holds a live one; it does not wait.
`tryAcquire(Duration)` → `boolean`	The waiting form: retries every 50ms until acquired or the timeout lapses. An interrupt during the wait restores the thread's interrupt flag and throws `LockException` rather than silently returning `false`.
`extend(ttlMs)` → `boolean`	Move the expiry to `ttlMs` from now. `false` means the lock was lost — expired or stolen — and `isHeld()` flips with it.
`release()` / `close()`	Give the lease up if held. Owner-scoped, so it never releases another holder's lock, and calling it twice is harmless.
`isHeld()` → `boolean`	The last verdict from `acquire()` or `extend`. A TTL that lapsed since is not noticed until the next call — `lockInfo(name)` is the authoritative answer.

A lock is a TTL lease, not a mutex, and nothing renews it for you: a holder that runs longer than ttlMs without calling extend loses the lease while still inside its critical section, and another owner may acquire. Size ttlMs against your worst case, or extend from inside a long body.

Periodic

Method	Description
`registerPeriodic(PeriodicTask)`	Register (or replace) a cron task → next fire time (Unix ms).
`listPeriodic()` / `deletePeriodic(name)` / `pausePeriodic(name)` / `resumePeriodic(name)`	Periodic task management.

Resources

Method	Description
`resource(...)`	Register an injectable resource.
`resource(name, ResourceDefinition)`	Register a pre-built definition — the escape hatch for knobs the typed overloads don't cover, such as `withReloadable(true)`.
`resourceMetrics()`	Per-resource created/disposed/active counters.
`reloadResources()` / `reloadResources(names)` → `Map<String, Boolean>`	Hot-reload resources: dispose what is cached, rebuild dependency-first. No argument sweeps every `withReloadable(true)` resource; an unknown name reports `false` rather than throwing. Empty when no worker is running — that is where the instances live.

Enqueue gates

Method	Description
`predicate(taskName, Predicate)` / `gate(taskName, EnqueueGate)`	Enqueue-time gates: reject, skip, or defer submissions.
`predicateStats()` → `PredicateStats`	Gate outcome counters: `allowed`, `skipped`, `deferred`, `rejected`, `errors`. One count per gated enqueue.
`intercept(Interceptor)`	Pass / convert / redirect / reject each enqueue before serialization.
`analyzeArguments(taskName, payload)` → `InterceptionAnalysis`	Dry-run the interceptor chain: what it would do, without enqueuing. A chain that would reject comes back as `rejected` instead of throwing.

Distributed locks

Method	Description
`lock(name, ttlMs)` / `lock(name)`	A distributed `Lock`, not yet acquired (default 30s TTL). Each instance mints its own owner id, so two handles on the same name contend rather than share.
`withLock(name, ttlMs, Runnable)` → `boolean`	Acquire → run → release, as try-with-resources. `false` means another owner held the lock and `body` never ran — it is a verdict, not a failure, so nothing is thrown.
`lockInfo(name)` (alias `getLockInfo`) → `Optional<LockInfo>`	The current holder: `lockName`, `ownerId`, `acquiredAt`, `expiresAt` (Unix milliseconds). Empty when the lock is free.

Lock is AutoCloseable and close() releases, so try-with-resources is the normal shape. Acquisition is never implicit — a handle you never acquire() guards nothing.

Method	Description
`acquire()` → `boolean`	Take the lease for this instance's owner id. `false` when another owner holds a live one; it does not wait.
`tryAcquire(Duration)` → `boolean`	The waiting form: retries every 50ms until acquired or the timeout lapses. An interrupt during the wait restores the thread's interrupt flag and throws `LockException` rather than silently returning `false`.
`extend(ttlMs)` → `boolean`	Move the expiry to `ttlMs` from now. `false` means the lock was lost — expired or stolen — and `isHeld()` flips with it.
`release()` / `close()`	Give the lease up if held. Owner-scoped, so it never releases another holder's lock, and calling it twice is harmless.
`isHeld()` → `boolean`	The last verdict from `acquire()` or `extend`. A TTL that lapsed since is not noticed until the next call — `lockInfo(name)` is the authoritative answer.

Method

Description

registerPeriodic(PeriodicTask)

listPeriodic() / deletePeriodic(name) / pausePeriodic(name) / resumePeriodic(name)

Periodic task management.