GitHub

ShardingService

API reference for ShardingService.

What Sharding provides. send delivers a message to a local entity, notify tells it a persisted message is waiting, and send_outgoing routes a message from a client.

Attributes

AttributeTypeDescription
get_registration_eventsStream[ShardingRegistrationEvent]

The entities and singletons registered from now on.

get_snowflakeEffect[Snowflake]

A new snowflake id, unique to this runner. Never fails.

is_shutdownEffect[bool]

Whether sharding is shutting down. Never fails.

poll_storageEffect[None]

Triggers a read of every unprocessed message in storage. Never fails.

active_entity_countEffect[int]

How many entities are running on this runner. Never fails.

Functions

get_shard_id

get_shard_id(entity_id, group) -> ShardId

The shard of group that entity_id belongs to.

ParameterTypeDescription
entity_idEntityId
groupstr

Returns ShardId

def get_shard_id(self, entity_id: EntityId, group: str, /) -> ShardId:
    """The shard of ``group`` that ``entity_id`` belongs to."""
    ...

has_shard_id

has_shard_id(shard_id) -> bool

Whether this runner holds shard_id (never while shutting down).

ParameterTypeDescription
shard_idShardId

Returns bool

def has_shard_id(self, shard_id: ShardId, /) -> bool:
    """Whether this runner holds ``shard_id`` (never while shutting
    down)."""
    ...

make_client

make_client[T: Entity](entity) -> Effect[Callable[[str], T]]

A function giving the client of entity for an entity id; its calls fail with MailboxFull, AlreadyProcessingMessage, PersistenceError or EntityNotAssignedToRunner. Making it never fails.

ParameterTypeDescription
entitytype[T]

Returns Effect[Callable[[str], T]]

def make_client[T: Entity](self, entity: type[T], /) -> Effect[Callable[[str], T]]:
    """A function giving the client of ``entity`` for an entity id;
    its calls fail with ``MailboxFull``, ``AlreadyProcessingMessage``,
    ``PersistenceError`` or ``EntityNotAssignedToRunner``. Making it
    never fails."""
    ...

register_entity

register_entity(entity, build, options) -> Effect[None, Never, Any]

Registers entity on this runner, its handlers built by build for each entity started, with options, until the Scope closes. Never fails.

ParameterTypeDescription
entitytype[Entity]
buildEffect[EntityHandlers[Any, Any], Never, Any]
optionsEntityOptions

Returns Effect[None, Never, Any]

def register_entity(
    self,
    entity: type[Entity],
    build: Effect[EntityHandlers[Any, Any], Never, Any],
    options: EntityOptions,
    /,
) -> Effect[None, Never, Any]:
    """Registers ``entity`` on this runner, its handlers built by
    ``build`` for each entity started, with ``options``, until the
    ``Scope`` closes. Never fails."""
    ...

register_singleton

register_singleton(name, run, shard_group) -> Effect[None, Never, Any]

Registers the singleton name: run runs on the runner that holds its shard of shard_group (None: "default"), until the Scope closes. Never fails; registering a name twice is a defect.

ParameterTypeDescription
namestr
runEffect[None, Any, Any]
shard_groupstr | None

Returns Effect[None, Never, Any]

def register_singleton(
    self, name: str, run: Effect[None, Any, Any], shard_group: str | None, /
) -> Effect[None, Never, Any]:
    """Registers the singleton ``name``: ``run`` runs on the runner that
    holds its shard of ``shard_group`` (``None``: ``"default"``), until
    the ``Scope`` closes. Never fails; registering a name twice is a
    defect."""
    ...

send

send(message) -> Effect[None, EntityNotAssignedToRunner | MailboxFull | AlreadyProcessingMessage]

Delivers message to its entity on this runner. Fails with EntityNotAssignedToRunner when its shard is not here, MailboxFull when the entity's mailbox is, and AlreadyProcessingMessage when the request is already being processed.

ParameterTypeDescription
messageIncoming

Returns Effect[None, EntityNotAssignedToRunner | MailboxFull | AlreadyProcessingMessage]

def send(
    self, message: Incoming, /
) -> Effect[None, EntityNotAssignedToRunner | MailboxFull | AlreadyProcessingMessage]:
    """Delivers ``message`` to its entity on this runner. Fails with
    ``EntityNotAssignedToRunner`` when its shard is not here,
    ``MailboxFull`` when the entity's mailbox is, and
    ``AlreadyProcessingMessage`` when the request is already being
    processed."""
    ...

send_outgoing

send_outgoing(message, discard) -> Effect[None, MailboxFull | AlreadyProcessingMessage | PersistenceError | EntityNotAssignedToRunner]

Routes message from a client to the runner of its entity (this one or another), persisting it first when it is persisted; discard drops its reply. Fails as send does, or with PersistenceError when storage fails.

ParameterTypeDescription
messageOutgoing
discardbool

Returns Effect[None, MailboxFull | AlreadyProcessingMessage | PersistenceError | EntityNotAssignedToRunner]

def send_outgoing(
    self, message: Outgoing, discard: bool, /
) -> Effect[
    None,
    MailboxFull | AlreadyProcessingMessage | PersistenceError | EntityNotAssignedToRunner,
]:
    """Routes ``message`` from a client to the runner of its entity
    (this one or another), persisting it first when it is persisted;
    ``discard`` drops its reply. Fails as ``send`` does, or with
    ``PersistenceError`` when storage fails."""
    ...

notify

notify(message, /, *, wait_until_read=False) -> Effect[None, EntityNotAssignedToRunner | AlreadyProcessingMessage]

Tells sharding that message was persisted, so storage is read for it; with wait_until_read, a request waits until that read has picked it up. Fails with EntityNotAssignedToRunner when its shard is not here, AlreadyProcessingMessage when the request is already being processed.

ParameterTypeDescription
messageIncoming
wait_until_readbool = False

Returns Effect[None, EntityNotAssignedToRunner | AlreadyProcessingMessage]

def notify(
    self, message: Incoming, /, *, wait_until_read: bool = False
) -> Effect[None, EntityNotAssignedToRunner | AlreadyProcessingMessage]:
    """Tells sharding that ``message`` was persisted, so storage is read
    for it; with ``wait_until_read``, a request waits until that read
    has picked it up. Fails with ``EntityNotAssignedToRunner`` when its
    shard is not here, ``AlreadyProcessingMessage`` when the request is
    already being processed."""
    ...

reset

reset(request_id, /, *, expected_reply_id=None) -> Effect[bool]

Clears the stored replies of request_id so it runs again; with expected_reply_id, only while that is still its latest reply. False when storage failed (it never fails), else True.

ParameterTypeDescription
request_idSnowflake
expected_reply_idSnowflake | None = None

Returns Effect[bool]

def reset(
    self, request_id: Snowflake, /, *, expected_reply_id: Snowflake | None = None
) -> Effect[bool]:
    """Clears the stored replies of ``request_id`` so it runs again;
    with ``expected_reply_id``, only while that is still its latest
    reply. ``False`` when storage failed (it never fails), else
    ``True``."""
    ...