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#
| Attribute | Type | Description |
|---|---|---|
get_registration_events | Stream[ShardingRegistrationEvent] | The entities and singletons registered from now on. |
get_snowflake | Effect[Snowflake] | A new snowflake id, unique to this runner. Never fails. |
is_shutdown | Effect[bool] | Whether sharding is shutting down. Never fails. |
poll_storage | Effect[None] | Triggers a read of every unprocessed message in storage. Never fails. |
active_entity_count | Effect[int] | How many entities are running on this runner. Never fails. |
Functions#
get_shard_id#
get_shard_id(entity_id, group) -> ShardIdThe shard of group that entity_id belongs to.
| Parameter | Type | Description |
|---|---|---|
entity_id | EntityId | |
group | str |
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) -> boolWhether this runner holds shard_id (never while shutting
down).
| Parameter | Type | Description |
|---|---|---|
shard_id | ShardId |
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.
| Parameter | Type | Description |
|---|---|---|
entity | type[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.
| Parameter | Type | Description |
|---|---|---|
entity | type[Entity] | |
build | Effect[EntityHandlers[Any, Any], Never, Any] | |
options | EntityOptions |
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.
| Parameter | Type | Description |
|---|---|---|
name | str | |
run | Effect[None, Any, Any] | |
shard_group | str | 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.
| Parameter | Type | Description |
|---|---|---|
message | Incoming |
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.
| Parameter | Type | Description |
|---|---|---|
message | Outgoing | |
discard | bool |
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.
| Parameter | Type | Description |
|---|---|---|
message | Incoming | |
wait_until_read | bool = 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.
| Parameter | Type | Description |
|---|---|---|
request_id | Snowflake | |
expected_reply_id | Snowflake | 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``."""
...