Where messages to entities and their replies are kept (Effect's
MessageStorage), with the reply handlers of this runner.
unprocessed_messages claims the messages it returns for ten
minutes; reset_* release claims early.
Attributes#
| Attribute | Type | Description |
|---|---|---|
base | StorageBase |
Functions#
__init__#
__init__(base, _handlers=dict[Snowflake, list[_ReplyHandler]](), _handlers_by_shard=dict[str, set[_ReplyHandler]]()) -> None| Parameter | Type | Description |
|---|---|---|
base | StorageBase | |
_handlers | dict[Snowflake, list[_ReplyHandler]] = dict[Snowflake, list[_ReplyHandler]]() | |
_handlers_by_shard | dict[str, set[_ReplyHandler]] = dict[str, set[_ReplyHandler]]() |
save_request#
save_request(message) -> Effect[SaveResult, PersistenceError | MalformedMessage]Saves the request message, or gives SaveDuplicate (with
the original's id and its last reply) when a request of the same
primary key is already stored. Fails with PersistenceError
when the storage cannot be written, MalformedMessage when the
message (or the stored reply) does not encode (or decode).
| Parameter | Type | Description |
|---|---|---|
message | OutgoingRequest |
Returns Effect[SaveResult, PersistenceError | MalformedMessage]
def save_request(
self, message: OutgoingRequest, /
) -> Effect[SaveResult, PersistenceError | MalformedMessage]:
"""Saves the request ``message``, or gives ``SaveDuplicate`` (with
the original's id and its last reply) when a request of the same
primary key is already stored. Fails with ``PersistenceError``
when the storage cannot be written, ``MalformedMessage`` when the
message (or the stored reply) does not encode (or decode)."""
return self.base.save_request(message)save_envelope#
save_envelope(message) -> Effect[None, PersistenceError | MalformedMessage]Saves the envelope message (an AckChunk or an
Interrupt). Fails with PersistenceError when the storage
cannot be written, MalformedMessage when it does not encode.
| Parameter | Type | Description |
|---|---|---|
message | OutgoingEnvelope |
Returns Effect[None, PersistenceError | MalformedMessage]
def save_envelope(
self, message: OutgoingEnvelope, /
) -> Effect[None, PersistenceError | MalformedMessage]:
"""Saves the envelope ``message`` (an ``AckChunk`` or an
``Interrupt``). Fails with ``PersistenceError`` when the storage
cannot be written, ``MalformedMessage`` when it does not encode."""
return self.base.save_envelope(message)clear_replies#
clear_replies(request_id, /, *, expected_reply_id=None) -> Effect[None, PersistenceError]Deletes the replies of request_id; with
expected_reply_id, only while that is still its latest reply
(so a stale resume cannot clear a newer one). Fails with
PersistenceError when the storage cannot be written.
| Parameter | Type | Description |
|---|---|---|
request_id | Snowflake | |
expected_reply_id | Snowflake | None = None |
Returns Effect[None, PersistenceError]
def clear_replies(
self, request_id: Snowflake, /, *, expected_reply_id: Snowflake | None = None
) -> Effect[None, PersistenceError]:
"""Deletes the replies of ``request_id``; with
``expected_reply_id``, only while that is still its latest reply
(so a stale resume cannot clear a newer one). Fails with
``PersistenceError`` when the storage cannot be written."""
return self.base.clear_replies(request_id, expected_reply_id=expected_reply_id)replies_for#
replies_for(requests) -> Effect[list[Reply], PersistenceError | MalformedMessage]The stored replies of requests that are still to be
delivered: their unacknowledged chunks and their WithExit.
Fails with PersistenceError when the storage cannot be read,
MalformedMessage when a reply does not decode.
| Parameter | Type | Description |
|---|---|---|
requests | Iterable[OutgoingRequest] |
Returns Effect[list[Reply], PersistenceError | MalformedMessage]
def replies_for(
self, requests: Iterable[OutgoingRequest], /
) -> Effect[list[Reply], PersistenceError | MalformedMessage]:
"""The stored replies of ``requests`` that are still to be
delivered: their unacknowledged chunks and their ``WithExit``.
Fails with ``PersistenceError`` when the storage cannot be read,
``MalformedMessage`` when a reply does not decode."""
return self.base.replies_for(requests)replies_for_unfiltered#
replies_for_unfiltered(request_ids) -> Effect[list[Any], PersistenceError | MalformedMessage]Every stored reply of request_ids, encoded. Fails with
PersistenceError when the storage cannot be read.
| Parameter | Type | Description |
|---|---|---|
request_ids | Iterable[Snowflake] |
Returns Effect[list[Any], PersistenceError | MalformedMessage]
def replies_for_unfiltered(
self, request_ids: Iterable[Snowflake], /
) -> Effect[list[Any], PersistenceError | MalformedMessage]:
"""Every stored reply of ``request_ids``, encoded. Fails with
``PersistenceError`` when the storage cannot be read."""
return self.base.replies_for_unfiltered(request_ids)request_id_for_primary_key#
request_id_for_primary_key(*, address, tag, id) -> Effect[Snowflake | None, PersistenceError]The id of the stored request to address with RPC tag
and primary key id, None when there is none. Fails with
PersistenceError when the storage cannot be read.
| Parameter | Type | Description |
|---|---|---|
address | EntityAddress | |
tag | str | |
id | str |
Returns Effect[Snowflake | None, PersistenceError]
def request_id_for_primary_key(
self, *, address: EntityAddress, tag: str, id: str
) -> Effect[Snowflake | None, PersistenceError]:
"""The id of the stored request to ``address`` with RPC ``tag``
and primary key ``id``, ``None`` when there is none. Fails with
``PersistenceError`` when the storage cannot be read."""
return self.base.request_id_for_primary_key(address=address, tag=tag, id=id)unprocessed_messages#
unprocessed_messages(shard_ids, /, *, limit=None, addresses=None) -> Effect[list[Incoming], PersistenceError]Claims, for ten minutes, the unprocessed messages of
shard_ids and gives them: requests without a WithExit or
with unacknowledged chunks, the latest AckChunk and the
Interrupt envelopes of unprocessed requests. limit bounds
how many one read gives, addresses restricts it to those
entities. A message that does not decode gets a defect reply
instead. Fails with PersistenceError when the storage cannot
be read.
| Parameter | Type | Description |
|---|---|---|
shard_ids | Iterable[ShardId] | |
limit | int | None = None | |
addresses | Sequence[EntityAddress] | None = None |
Returns Effect[list[Incoming], PersistenceError]
def unprocessed_messages(
self,
shard_ids: Iterable[ShardId],
/,
*,
limit: int | None = None,
addresses: Sequence[EntityAddress] | None = None,
) -> Effect[list[Incoming], PersistenceError]:
"""Claims, for ten minutes, the unprocessed messages of
``shard_ids`` and gives them: requests without a ``WithExit`` or
with unacknowledged chunks, the latest ``AckChunk`` and the
``Interrupt`` envelopes of unprocessed requests. ``limit`` bounds
how many one read gives, ``addresses`` restricts it to those
entities. A message that does not decode gets a defect reply
instead. Fails with ``PersistenceError`` when the storage cannot
be read."""
return self.base.unprocessed_messages(
shard_ids, responder=self, limit=limit, addresses=addresses
)unprocessed_messages_by_id#
unprocessed_messages_by_id(message_ids) -> Effect[list[Incoming], PersistenceError]The unprocessed messages among message_ids, claimed as
unprocessed_messages claims them. Fails with
PersistenceError when the storage cannot be read.
| Parameter | Type | Description |
|---|---|---|
message_ids | Iterable[Snowflake] |
Returns Effect[list[Incoming], PersistenceError]
def unprocessed_messages_by_id(
self, message_ids: Iterable[Snowflake], /
) -> Effect[list[Incoming], PersistenceError]:
"""The unprocessed messages among ``message_ids``, claimed as
``unprocessed_messages`` claims them. Fails with
``PersistenceError`` when the storage cannot be read."""
return self.base.unprocessed_messages_by_id(message_ids, responder=self)reset_shards#
reset_shards(shard_ids) -> Effect[None, PersistenceError]Releases the claims on the messages of shard_ids, so the
next read gives them again. Fails with PersistenceError when
the storage cannot be written.
| Parameter | Type | Description |
|---|---|---|
shard_ids | Iterable[ShardId] |
Returns Effect[None, PersistenceError]
def reset_shards(self, shard_ids: Iterable[ShardId], /) -> Effect[None, PersistenceError]:
"""Releases the claims on the messages of ``shard_ids``, so the
next read gives them again. Fails with ``PersistenceError`` when
the storage cannot be written."""
return self.base.reset_shards(shard_ids)reset_address#
reset_address(address) -> Effect[None, PersistenceError]Releases the claims on the messages to address. Fails with
PersistenceError when the storage cannot be written.
| Parameter | Type | Description |
|---|---|---|
address | EntityAddress |
Returns Effect[None, PersistenceError]
def reset_address(self, address: EntityAddress, /) -> Effect[None, PersistenceError]:
"""Releases the claims on the messages to ``address``. Fails with
``PersistenceError`` when the storage cannot be written."""
return self.base.reset_address(address)reset_requests#
reset_requests(request_ids) -> Effect[None, PersistenceError]Releases the claims on request_ids, leaving their replies
and processed state as they are. Fails with PersistenceError
when the storage cannot be written.
| Parameter | Type | Description |
|---|---|---|
request_ids | Sequence[Snowflake] |
Returns Effect[None, PersistenceError]
def reset_requests(self, request_ids: Sequence[Snowflake], /) -> Effect[None, PersistenceError]:
"""Releases the claims on ``request_ids``, leaving their replies
and processed state as they are. Fails with ``PersistenceError``
when the storage cannot be written."""
return self.base.reset_requests(request_ids)reset_addresses#
reset_addresses(addresses) -> Effect[None, PersistenceError]Releases the claims on the messages to addresses. Fails
with PersistenceError when the storage cannot be written.
| Parameter | Type | Description |
|---|---|---|
addresses | Sequence[EntityAddress] |
Returns Effect[None, PersistenceError]
def reset_addresses(
self, addresses: Sequence[EntityAddress], /
) -> Effect[None, PersistenceError]:
"""Releases the claims on the messages to ``addresses``. Fails
with ``PersistenceError`` when the storage cannot be written."""
return self.base.reset_addresses(addresses)clear_address#
clear_address(address) -> Effect[None, PersistenceError]Deletes every message to address and their replies. Fails
with PersistenceError when the storage cannot be written.
| Parameter | Type | Description |
|---|---|---|
address | EntityAddress |
Returns Effect[None, PersistenceError]
def clear_address(self, address: EntityAddress, /) -> Effect[None, PersistenceError]:
"""Deletes every message to ``address`` and their replies. Fails
with ``PersistenceError`` when the storage cannot be written."""
return self.base.clear_address(address)with_transaction#
with_transaction[A, E, R](effect) -> Effect[A, E, R]effect in one storage transaction; reply notifications wait
for the outermost commit.
| Parameter | Type | Description |
|---|---|---|
effect | Effect[A, E, R] |
Returns Effect[A, E, R]
def with_transaction[A, E, R](self, effect: Effect[A, E, R], /) -> Effect[A, E, R]:
"""``effect`` in one storage transaction; reply notifications wait
for the outermost commit."""
require_effect(effect, "effect")
def run(outer: list[Notification] | None) -> Effect[A, E, R]:
notifications: list[Notification] = []
def committed(_: A) -> Effect[None]:
if outer is not None:
pending = outer
return sync(lambda: pending.extend(notifications))
return for_each(notifications, lambda n: n).as_void().or_die()
inner = effect.pipe(provide_service(TransactionNotifications, notifications))
return self.base.with_transaction(inner).tap(committed)
return TransactionNotifications().flat_map(run)register_reply_handler#
register_reply_handler(message) -> Effect[None, EntityNotAssignedToRunner]Wait for the exit of message's request, sending every reply
saved meanwhile to it. Fails with EntityNotAssignedToRunner
when its shard's handlers are dropped.
| Parameter | Type | Description |
|---|---|---|
message | OutgoingRequest | IncomingRequest |
Returns Effect[None, EntityNotAssignedToRunner]
def register_reply_handler(
self, message: OutgoingRequest | IncomingRequest, /
) -> Effect[None, EntityNotAssignedToRunner]:
"""Wait for the exit of ``message``'s request, sending every reply
saved meanwhile to it. Fails with ``EntityNotAssignedToRunner``
when its shard's handlers are dropped."""
request_id = message.envelope.request_id
handlers_by_id = self._handlers
by_shard = self._handlers_by_shard
def register(resume: _Resume) -> Effect[None]:
shard = str(message.envelope.address.shard_id)
handlers = handlers_by_id.setdefault(request_id, [])
shard_set = by_shard.setdefault(shard, set())
entry = _ReplyHandler(message, shard_set, resume)
handlers.append(entry)
shard_set.add(entry)
def unregister() -> None:
if entry in handlers:
handlers.remove(entry)
shard_set.discard(entry)
return sync(unregister)
return callback(register)unregister_reply_handler#
unregister_reply_handler(request_id, /, *, interrupt=False) -> Effect[None]Drop the handlers of request_id: they fail with
EntityNotAssignedToRunner, or are interrupted as abandoned.
| Parameter | Type | Description |
|---|---|---|
request_id | Snowflake | |
interrupt | bool = False |
Returns Effect[None]
def unregister_reply_handler(
self, request_id: Snowflake, /, *, interrupt: bool = False
) -> Effect[None]:
"""Drop the handlers of ``request_id``: they fail with
``EntityNotAssignedToRunner``, or are interrupted as abandoned."""
def run() -> None:
handlers = self._handlers.pop(request_id, None)
for handler in handlers or ():
handler.shard_set.discard(handler)
self._resume_unregistered(handler, interrupt)
return sync(run)unregister_shard_reply_handlers#
unregister_shard_reply_handlers(shard_id, /, *, interrupt=False) -> Effect[None]Drop the handlers of every request to shard_id.
| Parameter | Type | Description |
|---|---|---|
shard_id | ShardId | |
interrupt | bool = False |
Returns Effect[None]
def unregister_shard_reply_handlers(
self, shard_id: ShardId, /, *, interrupt: bool = False
) -> Effect[None]:
"""Drop the handlers of every request to ``shard_id``."""
def run() -> None:
shard_set = self._handlers_by_shard.pop(str(shard_id), None)
for handler in list(shard_set or ()):
self._handlers.pop(handler.message.envelope.request_id, None)
self._resume_unregistered(handler, interrupt)
return sync(run)save_reply#
save_reply(reply) -> Effect[None, PersistenceError | MalformedMessage]Persist reply and send it to the request's handlers; an exit
resumes them (after the outermost commit, in a transaction).
| Parameter | Type | Description |
|---|---|---|
reply | ReplyWithContext |
Returns Effect[None, PersistenceError | MalformedMessage]
def save_reply(
self, reply: ReplyWithContext, /
) -> Effect[None, PersistenceError | MalformedMessage]:
"""Persist ``reply`` and send it to the request's handlers; an exit
resumes them (after the outermost commit, in a transaction)."""
request_id = reply.reply.request_id
def persisted(saved: ReplyWithContext) -> Effect[None, PersistenceError | MalformedMessage]:
def notify_now() -> Notification:
handlers = self._handlers.get(request_id)
if handlers is None:
return void
if isinstance(saved.reply, WithExit):
del self._handlers[request_id]
for handler in handlers:
handler.shard_set.discard(handler)
handler.resume(void)
if len(handlers) == 1:
return handlers[0].respond(saved)
return for_each(list(handlers), lambda h: h.respond(saved)).as_void()
notify = suspend(notify_now)
if not isinstance(saved.reply, WithExit):
return notify
def defer(notifications: list[Notification] | None) -> Notification:
if notifications is None:
return notify
return sync(lambda: notifications.append(notify))
return TransactionNotifications().flat_map(defer)
return self.base.save_reply(reply).flat_map(persisted)On This Page
AttributesFunctions__init__save_requestsave_envelopeclear_repliesreplies_forreplies_for_unfilteredrequest_id_for_primary_keyunprocessed_messagesunprocessed_messages_by_idreset_shardsreset_addressreset_requestsreset_addressesclear_addresswith_transactionregister_reply_handlerunregister_reply_handlerunregister_shard_reply_handlerssave_reply