GitHub

MemoryEncoded

API reference for MemoryEncoded.

The memory driver's EncodedStorage. Envelopes are kept by identity: the journal, the unprocessed set and the claims hold the same dictionaries.

Attributes

AttributeTypeDescription
requestsdict[str, MemoryEntry] = {}
requests_by_primary_keydict[str, MemoryEntry] = {}
unprocesseddict[int, EnvelopeEncoded] = {}
reply_idsset[str] = set()
last_readdict[int, int] = {}
journallist[EnvelopeEncoded] = []

Functions

__init__

__init__(clock) -> None
ParameterTypeDescription
clockClockService
def __init__(self, clock: ClockService) -> None:
    self._clock = clock
    self.requests: dict[str, MemoryEntry] = {}
    self.requests_by_primary_key: dict[str, MemoryEntry] = {}
    self.unprocessed: dict[int, EnvelopeEncoded] = {}
    self.reply_ids: set[str] = set()
    self.last_read: dict[int, int] = {}
    self.journal: list[EnvelopeEncoded] = []

save_envelope

save_envelope(envelope, primary_key, deliver_at) -> Effect[SaveResultEncoded, PersistenceError]
ParameterTypeDescription
envelopeEnvelopeEncoded
primary_keystr | None
deliver_atint | None

Returns Effect[SaveResultEncoded, PersistenceError]

def save_envelope(
    self, envelope: EnvelopeEncoded, primary_key: str | None, deliver_at: int | None, /
) -> Effect[SaveResultEncoded, PersistenceError]:
    def run() -> SaveResultEncoded:
        stored = json_copy(envelope)
        if primary_key:
            existing = self.requests_by_primary_key.get(primary_key)
        elif stored["_tag"] == "Request":
            existing = self.requests.get(stored["requestId"])
        else:
            existing = None
        if existing is not None:
            replies = existing.replies
            last = (
                replies[0]
                if len(replies) == 1 and replies[0]["_tag"] == "WithExit"
                else existing.last_received_chunk
            )
            return DuplicateEncoded(
                original_id=Snowflake(int(existing.envelope["requestId"])),
                last_received_reply=last,
            )
        if stored["_tag"] == "Request":
            entry = MemoryEntry(stored, deliver_at)
            self.requests[stored["requestId"]] = entry
            if primary_key:
                self.requests_by_primary_key[primary_key] = entry
        elif stored["_tag"] == "AckChunk":
            entry = self.requests.get(stored["requestId"])
            if entry is not None:
                reply_id = stored["replyId"]
                for r in entry.replies:
                    if r["_tag"] == "Chunk" and r["id"] == reply_id:
                        entry.last_received_chunk = r
                        break
        self.unprocessed[id(stored)] = stored
        self.journal.append(stored)
        return SAVE_SUCCESS

    return sync(run)

save_reply

save_reply(reply) -> Effect[None, PersistenceError]
ParameterTypeDescription
replyreply_.Encoded

Returns Effect[None, PersistenceError]

def save_reply(self, reply: reply_.Encoded, /) -> Effect[None, PersistenceError]:
    def run() -> None:
        stored = json_copy(reply)
        entry = self.requests.get(stored["requestId"])
        if entry is None or stored["id"] in self.reply_ids:
            return
        if stored["_tag"] == "WithExit":
            self.unprocessed.pop(id(entry.envelope), None)
            self.last_read.pop(id(entry.envelope), None)
        entry.replies.append(stored)
        self.reply_ids.add(stored["id"])

    save = sync(run)

    # Memory has no transaction isolation: an exit is published at the
    # outer commit, before its queued handler notifications, so readers
    # cannot see a success that may still be rolled back.
    def deferred(notifications: Any) -> Effect[None]:
        if reply["_tag"] == "WithExit" and notifications is not None:
            pending: list[Any] = notifications
            return sync(lambda: pending.append(save))
        return save

    return TransactionNotifications().flat_map(deferred)

clear_replies

clear_replies(request_id, /, *, expected_reply_id=None) -> Effect[None, PersistenceError]
ParameterTypeDescription
request_idSnowflake
expected_reply_idSnowflake | None = None

Returns Effect[None, PersistenceError]

def clear_replies(
    self, request_id: Snowflake, /, *, expected_reply_id: Snowflake | None = None
) -> Effect[None, PersistenceError]:
    def run() -> None:
        entry = self.requests.get(str(request_id))
        if entry is None:
            return
        if expected_reply_id is not None and (
            not entry.replies or entry.replies[-1]["id"] != str(expected_reply_id)
        ):
            return
        entry.replies = []
        entry.last_received_chunk = None
        self.unprocessed[id(entry.envelope)] = entry.envelope
        self.last_read.pop(id(entry.envelope), None)

    return sync(run)

request_id_for_primary_key

request_id_for_primary_key(primary_key) -> Effect[Snowflake | None, PersistenceError]
ParameterTypeDescription
primary_keystr

Returns Effect[Snowflake | None, PersistenceError]

def request_id_for_primary_key(
    self, primary_key: str, /
) -> Effect[Snowflake | None, PersistenceError]:
    def run() -> Snowflake | None:
        entry = self.requests_by_primary_key.get(primary_key)
        return None if entry is None else Snowflake(int(entry.envelope["requestId"]))

    return sync(run)

replies_for

replies_for(request_ids) -> Effect[list[reply_.Encoded], PersistenceError]
ParameterTypeDescription
request_idsSequence[str]

Returns Effect[list[reply_.Encoded], PersistenceError]

def replies_for(
    self, request_ids: Sequence[str], /
) -> Effect[list[reply_.Encoded], PersistenceError]:
    def run() -> list[reply_.Encoded]:
        replies: list[reply_.Encoded] = []
        for request_id in request_ids:
            entry = self.requests.get(request_id)
            if entry is None:
                continue
            chunk = entry.last_received_chunk
            if chunk is None:
                replies.extend(entry.replies)
                continue
            for r in entry.replies:
                if r["_tag"] == "Chunk" and r["sequence"] <= chunk["sequence"]:
                    continue
                replies.append(r)
        return replies

    return sync(run)

replies_for_unfiltered

replies_for_unfiltered(request_ids) -> Effect[list[reply_.Encoded], PersistenceError]
ParameterTypeDescription
request_idsSequence[str]

Returns Effect[list[reply_.Encoded], PersistenceError]

def replies_for_unfiltered(
    self, request_ids: Sequence[str], /
) -> Effect[list[reply_.Encoded], PersistenceError]:
    def run() -> list[reply_.Encoded]:
        replies: list[reply_.Encoded] = []
        for request_id in request_ids:
            entry = self.requests.get(request_id)
            if entry is not None:
                replies.extend(entry.replies)
        return replies

    return sync(run)

unprocessed_messages

unprocessed_messages(shard_ids, now, /, *, limit=None, addresses=None) -> Effect[list[EncodedMessage], PersistenceError]
ParameterTypeDescription
shard_idsSequence[str]
nowint
limitint | None = None
addressesSequence[EntityAddress] | None = None

Returns Effect[list[EncodedMessage], PersistenceError]

def unprocessed_messages(
    self,
    shard_ids: Sequence[str],
    now: int,
    /,
    *,
    limit: int | None = None,
    addresses: Sequence[EntityAddress] | None = None,
) -> Effect[list[EncodedMessage], PersistenceError]:
    if addresses is not None and len(addresses) == 0:
        return succeed([])

    def run() -> list[EncodedMessage]:
        if not self.unprocessed:
            return []
        address_filter = None if addresses is None else {_address_key(a) for a in addresses}
        shards = set(shard_ids)
        messages: list[EncodedMessage] = []
        for envelope in list(self.journal):
            if limit is not None and len(messages) >= limit:
                break
            key = id(envelope)
            if key not in self.unprocessed or _shard_key(envelope["address"]) not in shards:
                continue
            if (
                address_filter is not None
                and _address_key(envelope["address"]) not in address_filter
            ):
                continue
            if envelope["_tag"] == "Request":
                entry = self.requests[envelope["requestId"]]
                if entry.deliver_at and entry.deliver_at > now:
                    continue
                claimed_at = self.last_read.get(key)
                if claimed_at is not None and claimed_at > now - CLAIM_EXPIRATION_MILLIS:
                    continue
                last = entry.replies[-1] if entry.replies else None
                messages.append(EncodedMessage(envelope, last))
                self.last_read[key] = now
            else:
                messages.append(EncodedMessage(envelope, None))
                del self.unprocessed[key]
        return messages

    return sync(run)

unprocessed_messages_by_id

unprocessed_messages_by_id(message_ids, now) -> Effect[list[EncodedMessage], PersistenceError]
ParameterTypeDescription
message_idsSequence[Snowflake]
nowint

Returns Effect[list[EncodedMessage], PersistenceError]

def unprocessed_messages_by_id(
    self, message_ids: Sequence[Snowflake], now: int, /
) -> Effect[list[EncodedMessage], PersistenceError]:
    ids = {str(i) for i in message_ids}
    return sync(lambda: self._unprocessed_with(lambda e: e["requestId"] in ids))

reset_requests

reset_requests(request_ids) -> Effect[None, PersistenceError]
ParameterTypeDescription
request_idsSequence[Snowflake]

Returns Effect[None, PersistenceError]

def reset_requests(self, request_ids: Sequence[Snowflake], /) -> Effect[None, PersistenceError]:
    def run() -> None:
        for request_id in request_ids:
            entry = self.requests.get(str(request_id))
            if entry is not None:
                self.last_read.pop(id(entry.envelope), None)

    return sync(run)

reset_addresses

reset_addresses(addresses) -> Effect[None, PersistenceError]
ParameterTypeDescription
addressesSequence[EntityAddress]

Returns Effect[None, PersistenceError]

def reset_addresses(
    self, addresses: Sequence[EntityAddress], /
) -> Effect[None, PersistenceError]:
    if not addresses:
        return succeed(None)

    def run() -> None:
        keys = {_address_key(a) for a in addresses}
        for envelope in self.journal:
            if _address_key(envelope["address"]) in keys:
                self.last_read.pop(id(envelope), None)

    return sync(run)

clear_address

clear_address(address) -> Effect[None, PersistenceError]
ParameterTypeDescription
addressEntityAddress

Returns Effect[None, PersistenceError]

def clear_address(self, address: EntityAddress, /) -> Effect[None, PersistenceError]:
    def run() -> None:
        for primary_key, entry in list(self.requests_by_primary_key.items()):
            if _same_entity(address, entry.envelope["address"]):
                del self.requests_by_primary_key[primary_key]
        kept: list[EnvelopeEncoded] = []
        for envelope in self.journal:
            if not _same_entity(address, envelope["address"]):
                kept.append(envelope)
                continue
            self.unprocessed.pop(id(envelope), None)
            self.last_read.pop(id(envelope), None)
            if envelope["_tag"] == "Request":
                self.requests.pop(envelope["requestId"], None)
        self.journal[:] = kept

    return sync(run)

reset_shards

reset_shards(shard_ids) -> Effect[None, PersistenceError]
ParameterTypeDescription
shard_idsSequence[str]

Returns Effect[None, PersistenceError]

def reset_shards(self, shard_ids: Sequence[str], /) -> Effect[None, PersistenceError]:
    def run() -> None:
        shards = set(shard_ids)
        for envelope in self.journal:
            if _shard_key(envelope["address"]) in shards:
                self.last_read.pop(id(envelope), None)

    return sync(run)

with_transaction

with_transaction[A, E, R](effect) -> Effect[A, E, R]
ParameterTypeDescription
effectEffect[A, E, R]

Returns Effect[A, E, R]

def with_transaction[A, E, R](self, effect: Effect[A, E, R], /) -> Effect[A, E, R]:
    require_effect(effect, "effect")
    return effect.pipe(provide_service(MemoryTransaction, True))