/ 
Discord-Client-0.001
/ Discord::Client::Cache

NAME

Discord::Client::Cache - Bounded resource snapshots

SYNOPSIS

use Discord::Client::Cache;

# Store bounded snapshots without network I/O.
my $cache = Discord::Client::Cache->new(
    types => ['channel', 'message'], max_items => 1000, ttl => 300,
);
$cache->put(message => $data);
my $message = $cache->get(message => $message_id);

DESCRIPTION

Optional in-memory snapshots of observed resources. All methods are synchronous and perform no requests. In Discord::Client, enable caching with cache => 1, an options hash or an existing Cache object. It is off by default.

The client applies Gateway events before calling application handlers. Snapshots may be partial, stale or missing. REST fetches do not automatically populate the cache. Client shutdown leaves snapshots until cleared or expired. A supplied cache can be shared by clients on the same loop.

METHODS

new

Returns an empty cache. types accepts an arrayref of guild, channel, user and message; omitting it selects all four. Invalid options throw. clock can supply a monotonic clock callback for testing.

max_items

Maximum entries; default 1000.

ttl

Seconds since the last write; default 300.

max_bytes

Total serialized JSON bytes; default 8388608.

max_entry_bytes

Serialized bytes per entry; default 262144.

Reads refresh least-recently-used order. Total limits evict the least recently used entries. Oversized entries are rejected and remove any older snapshot. Perl object overhead is not included in byte counts. Expiry runs on reads, writes and stats; there are no background timers.

put

put(type, hashref, merge => 1) stores copied JSON data with an ID. Returns true when stored, false for disabled types or oversized entries. Invalid IDs, types or data throw. merge combines top-level fields with an existing entry, including explicit nulls; otherwise data is replaced. Unknown fields are preserved.

get

get(type, id) returns a copied hashref or undef when absent or expired. IDs are decimal strings.

remove

remove(type, id) removes an entry and returns whether it existed.

apply

apply(event_name, payload_hash) updates observed objects from a Gateway event. Returns no value. Deletes remove related entries; guild outages retain snapshots marked unavailable until expiry.

Guild snapshots omit members, presences, voice states, channels and threads. Observed channels and threads have separate entries. There are no guild/member scans, presence or voice-state caches.

clear

Removes all entries and returns no value.

stats

Expires old entries and returns a hashref of counters, entry count and serialized-byte usage.

LICENSE

Apache License 2.0.