Class ManagedAdmissionController

java.lang.Object

org.j7m.middleware.application.components.ManagedAdmissionController

All Implemented Interfaces:

AutoCloseable

public final class ManagedAdmissionController
extends Object
implements AutoCloseable

Host-local bounded admission with non-preemptive priority and ageing.

No worker threads are created. Waiting callers consume at most the configured queue capacity and observe a monotonic time budget or interruption. Closing rejects queued/new callers but does not cancel running work or release its permits. The owner must close each permit only when physical work completes, including exceptional asynchronous completion. This is a JVM-local budget, not a distributed semaphore or CPU scheduler. Instances are thread-safe.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
final class	ManagedAdmissionController.Permit	Idempotent permit which may be released by another completion thread.
static final record	ManagedAdmissionController.Status	Atomic aggregate host-local counters.

Constructor Summary

Constructors

Constructor	Description
ManagedAdmissionController(int capacity, int maximumQueued, Duration ageingStep)	Creates a shared host budget.

Method Summary

Modifier and Type	Method	Description
ManagedAdmissionController.Permit	acquire(int priority, Duration timeout)	Acquires one permit, preferring higher relative priority with FIFO ties and ageing.
void	close()	Rejects queued and future admissions; running permits retain their accounting until closed.
ManagedAdmissionController.Status	status()	Returns aggregate counters without request/argument information.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

ManagedAdmissionController

public ManagedAdmissionController(int capacity,
 int maximumQueued,
 Duration ageingStep)

Creates a shared host budget.

Parameters:

capacity - simultaneous active permits, 1 through 1000000

maximumQueued - maximum waiting callers, 0 through 1024

ageingStep - positive interval after which a waiting caller gains one relative priority unit

Throws:

IllegalArgumentException - if bounds or the ageing interval are invalid

NullPointerException - if ageingStep is null

Method Details

acquire

public ManagedAdmissionController.Permit acquire(int priority,
 Duration timeout)

Acquires one permit, preferring higher relative priority with FIFO ties and ageing. New callers never bypass the queue through the immediate fast path. Once queued, a higher priority may overtake lower priorities. Ageing improves fairness within the waiting budget; it does not guarantee admission under sustained overload. A zero budget permits immediate acquisition only; a saturated queue rejects immediately. Interruption rejects admission without clearing the thread's interrupt status. An acquired permit remains active until explicitly closed.

Parameters:

priority - relative priority, -1024 through 1024

timeout - maximum monotonic waiting time, zero through one minute

Returns:

owned idempotent permit

Throws:

IllegalArgumentException - for an invalid priority or timeout

org.j7m.middleware.api.MiddlewareException - OVERLOADED for capacity rejection, DEADLINE_EXCEEDED for elapsed waiting time, CANCELLED for interruption, or UNAVAILABLE when closed

status

public ManagedAdmissionController.Status status()

Returns aggregate counters without request/argument information.

Returns:

atomic host-local admission state

close

public void close()

Rejects queued and future admissions; running permits retain their accounting until closed.

Specified by:

close in interface AutoCloseable