Resource

Shared contended resources with acquire/release semantics and FIFO waiters.

Shared resource with contended capacity.

Provides a Resource class for modeling shared, contended capacity such as CPU cores, memory bandwidth, disk I/O, or network bandwidth. Multiple entities can acquire portions of a resource's capacity, blocking via SimFuture when capacity is exhausted.

Like other simulation primitives (Mutex, Semaphore), Resource is an Entity and must be registered with Simulation(entities=[...]).

Example::

resource = Resource("cpu_cores", capacity=8)

class Worker(Entity):
    def handle_event(self, event):
        grant = yield resource.acquire(amount=2)  # blocks if unavailable
        yield 0.1  # do work
        grant.release()  # return capacity, wake waiters
        return []

sim = Simulation(entities=[resource, worker], ...)

ResourceStats dataclass

ResourceStats(
    name: str = "",
    capacity: int | float = 0,
    available: int | float = 0,
    utilization: float = 0.0,
    acquisitions: int = 0,
    releases: int = 0,
    contentions: int = 0,
    waiters: int = 0,
    total_wait_time_ns: int = 0,
    peak_utilization: float = 0.0,
    peak_waiters: int = 0,
)

Frozen snapshot of resource statistics.

Attributes:

Name	Type	Description
name	str	Resource name.
capacity	int | float	Total capacity of the resource.
available	int | float	Currently available capacity.
utilization	float	Fraction of capacity in use (0.0 to 1.0).
acquisitions	int	Total successful acquisitions.
releases	int	Total releases.
contentions	int	Times a waiter had to queue (capacity was insufficient).
waiters	int	Current number of waiting acquirers.
total_wait_time_ns	int	Total nanoseconds spent waiting across all waiters.
peak_utilization	float	Highest utilization observed.
peak_waiters	int	Maximum concurrent waiters observed.

Grant

Grant(resource: Resource, amount: int | float)

Handle to acquired resource capacity.

A Grant represents capacity that has been acquired from a Resource. Call release() to return the capacity. Release is idempotent — calling it multiple times has no effect after the first call.

Attributes:

Name	Type	Description
amount	int | float	The amount of capacity held by this grant.
released	bool	Whether this grant has been released.

amount property

amount: int | float

The amount of capacity held by this grant.

released property

released: bool

Whether this grant has been released.

release

release() -> None

Return capacity to the resource and wake waiting acquirers.

Idempotent — calling release() on an already-released grant is a no-op.

Resource

Resource(name: str, capacity: int | float)

Bases: Entity

Shared capacity pool that multiple entities can acquire from.

Resource models shared, contended capacity such as CPU cores, memory, disk I/O bandwidth, or network bandwidth. Entities acquire capacity via yield resource.acquire(amount) which returns a SimFuture that resolves with a Grant object.

Like other simulation primitives (Mutex, Semaphore), Resource is an Entity and must be registered with Simulation(entities=[...]).

Waiter satisfaction is strict FIFO: when capacity is released, only the head-of-line waiter is checked. If it needs more capacity than is available, no subsequent waiters are served (prevents starvation of large requests).

Parameters:

Name	Type	Description	Default
name	str	Identifier for logging and stats.	required
capacity	int | float	Total capacity of the resource (must be > 0).	required

Raises:

Type	Description
ValueError	If capacity is not positive.

capacity property

capacity: int | float

Total capacity of the resource.

available property

available: int | float

Currently available capacity.

utilization property

utilization: float

Fraction of capacity currently in use (0.0 to 1.0).

waiters property

waiters: int

Number of entities waiting to acquire capacity.

stats property

stats: ResourceStats

Frozen snapshot of current resource statistics.

acquire

acquire(amount: int | float = 1) -> SimFuture

Acquire capacity, returning a SimFuture that resolves with a Grant.

If sufficient capacity is available, the returned future is pre-resolved (yielding it resumes immediately). Otherwise the caller is queued and the future resolves when capacity becomes available via FIFO ordering.

Parameters:

Name	Type	Description	Default
amount	int | float	Amount of capacity to acquire (default 1).	1

Returns:

Type	Description
SimFuture	A SimFuture that resolves with a Grant object.

Raises:

Type	Description
ValueError	If amount is not positive or exceeds total capacity.

try_acquire

try_acquire(amount: int | float = 1) -> Grant | None

Try to acquire capacity without blocking.

Parameters:

Name	Type	Description	Default
amount	int | float	Amount of capacity to acquire (default 1).	1

Returns:

Type	Description
Grant | None	A Grant if capacity was available, None otherwise.

Raises:

Type	Description
ValueError	If amount is not positive or exceeds total capacity.

handle_event

handle_event(event: Event) -> None

Resource does not process events directly.