Skip to content

hikari-arc documentation

Concurrency Limiters

Concurrency Limiters#

This module contains the default concurrency limiter implementation in arc along with several helper functions to create common variants of it.

Note

Concurrency limiters are not regular hooks and need a special decorator to be set. You can only have 1 concurrency limiter per command.

CommandConcurrencyLimiter #

CommandConcurrencyLimiter(
    capacity: int, *, get_key_with: Callable[[KeyT], str]
)

Bases: ConcurrencyLimiter[Context[ClientT]], ConcurrencyLimiterProto[ClientT]

A concurrency limiter specialized for use with arc commands. This limiter only accepts arc.context.Context instances as keys.

For a generic implementation that works with any key type, see ConcurrencyLimiter.

PARAMETER	DESCRIPTION
`capacity`	The maximum amount of concurrently running command instances. TYPE: `int`
`get_key_with`	A callable that returns a key for the concurrency limiter bucket. TYPE: `Callable[[Context[ClientT]], str]`

See Also

guild_concurrency()
channel_concurrency()
user_concurrency()
member_concurrency()
custom_concurrency()

limit `property` #

limit: int

The maximum amount of concurrently running requests.

call #

__call__(
    item: Context[ClientT],
) -> _ConcurrencyLimiterContextManager[Context[ClientT]]

Use the limiter as a context manager.

This will acquire a concurrency slot for an item and release it when the context exits.

Example:

limiter = arc.utils.CommandConcurrencyLimiter(5, lambda ctx: str(ctx.guild_id)))

async with limiter(ctx):
    print("ctx is now being processed")

This is equivalent to:

limiter = arc.utils.CommandConcurrencyLimiter(5, lambda ctx: str(ctx.guild_id)))

try:
    await limiter.acquire(ctx)
    print("ctx is now being processed")
finally:
    await limiter.release(ctx)

acquire `async` #

acquire(item: KeyT) -> None

Acquire a concurrency slot for an item.

This will block until a slot is available.

is_exhausted #

is_exhausted(item: KeyT) -> bool

Return a boolean determining if the limiter is exhausted for an item.

release #

release(item: KeyT) -> None

Release a concurrency slot for an item.

ConcurrencyLimiter #

ConcurrencyLimiter(capacity: int, *, get_key_with: Callable[[KeyT], str])

Bases: Generic[KeyT]

A general purpose concurrency limiter. Accepts a key extraction function and allocates buckets for each unique key.

Example:

limiter = arc.utils.ConcurrencyLimiter[int](
    capacity=5,
    get_key_with=lambda x: str(x),
)

async with limiter(69):
    print("69 is now being processed")

Note

For use with commands, see CommandConcurrencyLimiter.

PARAMETER	DESCRIPTION
`capacity`	The maximum amount of concurrently running requests. TYPE: `int`
`get_key_with`	A callable that returns a key for the concurrency limiter bucket. TYPE: `Callable[[KeyT], str]`

See Also

CommandConcurrencyLimiter
guild_concurrency()
channel_concurrency()
user_concurrency()
member_concurrency()
custom_concurrency()

limit `property` #

limit: int

The maximum amount of concurrently running requests.

call #

__call__(item: KeyT) -> _ConcurrencyLimiterContextManager[KeyT]

Use the limiter as a context manager.

This will acquire a concurrency slot for an item and release it when the context exits.

Example:

limiter = arc.utils.ConcurrencyLimiter[str](5, lambda x: x)

async with limiter("foo"):
    print("foo is now being processed")

This is equivalent to:

limiter = arc.utils.ConcurrencyLimiter[str](5, lambda x: x)

try:
    await limiter.acquire("foo")
    print("foo is now being processed")
finally:
    await limiter.release("foo")

acquire `async` #

acquire(item: KeyT) -> None

Acquire a concurrency slot for an item.

This will block until a slot is available.

is_exhausted #

is_exhausted(item: KeyT) -> bool

Return a boolean determining if the limiter is exhausted for an item.

release #

release(item: KeyT) -> None

Release a concurrency slot for an item.

channel_concurrency #

channel_concurrency(limit: int) -> CommandConcurrencyLimiter[Any]

Limit a command to a certain amount of concurrent instances per channel.

PARAMETER	DESCRIPTION
`limit`	The maximum amount of concurrently running command instances. TYPE: `int`

RETURNS	DESCRIPTION
`CommandConcurrencyLimiter[Any]`	A concurrency limiter for use with a command.

Example

@arc.with_concurrency_limit(arc.channel_concurrency(1))

custom_concurrency #

custom_concurrency(
    limit: int, get_key_with: Callable[[Context[ClientT]], str]
) -> CommandConcurrencyLimiter[Any]

Limit a command to a certain amount of concurrent instances per custom key.

PARAMETER	DESCRIPTION
`limit`	The maximum amount of concurrently running command instances. TYPE: `int`
`get_key_with`	A callable that returns a key for the concurrency limiter bucket. TYPE: `Callable[[Context[ClientT]], str]`

RETURNS	DESCRIPTION
`CommandConcurrencyLimiter[Any]`	A concurrency limiter for use with a command.

Example

# This is identical to 'arc.guild_concurrency(1)'
@arc.with_concurrency_limit(arc.custom_concurrency(1, lambda ctx: str(ctx.guild_id)))

global_concurrency #

global_concurrency(limit: int) -> CommandConcurrencyLimiter[Any]

Limit a command to a certain amount of concurrent instances globally.

PARAMETER	DESCRIPTION
`limit`	The maximum amount of concurrently running command instances. TYPE: `int`

RETURNS	DESCRIPTION
`CommandConcurrencyLimiter[Any]`	A concurrency limiter for use with a command.

Example

@arc.with_concurrency_limit(arc.global_concurrency(1))

guild_concurrency #

guild_concurrency(limit: int) -> CommandConcurrencyLimiter[Any]

Limit a command to a certain amount of concurrent instances per guild.

PARAMETER	DESCRIPTION
`limit`	The maximum amount of concurrently running command instances. TYPE: `int`

RETURNS	DESCRIPTION
`CommandConcurrencyLimiter[Any]`	A concurrency limiter for use with a command.

Example

@arc.with_concurrency_limit(arc.guild_concurrency(1))

member_concurrency #

member_concurrency(limit: int) -> CommandConcurrencyLimiter[Any]

Limit a command to a certain amount of concurrent instances per member.

PARAMETER	DESCRIPTION
`limit`	The maximum amount of concurrently running command instances. TYPE: `int`

RETURNS	DESCRIPTION
`CommandConcurrencyLimiter[Any]`	A concurrency limiter for use with a command.

Example

@arc.with_concurrency_limit(arc.member_concurrency(1))

user_concurrency #

user_concurrency(limit: int) -> CommandConcurrencyLimiter[Any]

Limit a command to a certain amount of concurrent instances per user.

PARAMETER	DESCRIPTION
`limit`	The maximum amount of concurrently running command instances. TYPE: `int`

RETURNS	DESCRIPTION
`CommandConcurrencyLimiter[Any]`	A concurrency limiter for use with a command.

Example

@arc.with_concurrency_limit(arc.user_concurrency(1))