Nostrum.Cache.PresenceCache behaviour (nostrum v0.11.0-dev)
View SourceCache behaviour & dispatcher for Discord presences.
By default, Elixir.Nostrum.Cache.PresenceCache.ETS will be use for caching
presences. You can override this in the :caches option of the nostrum
application by setting the :presences fields to a different module
implementing the Nostrum.Cache.PresenceCache behaviour. Any module below
Nostrum.Cache.PresenceCache implements this behaviour and can be used as a
cache.
Writing your own presence cache
As with the other caches, the presence cache API consists of three parts:
The functions that nostrum calls, such as
create/1orupdate/1. These do not create any objects in the Discord API, they are purely created to update the cached data from data that Discord sends us. If you want to create objects on Discord, use the functions exposed byNostrum.Apiinstead.the callbacks for read operations, also documented in this module, and
the
child_spec/1callback for starting the cache under a supervisor.
You need to implement both of them for nostrum to work with your custom cache.
Summary
Types
Represents a presence as received from Discord. See Presence Update.
Callbacks
Bulk create multiple presences for the given guild in the cache.
Retrieve the child specification for starting this mapping under a supervisor.
Create a presence in the cache.
Update the given presence in the cache from upstream data.
A function that should wrap any :qlc operations.
Functions
Retrieves a presence for a user from the cache by guild and id.
Same as get/1, but raise Nostrum.Error.CacheError in case of a failure.
Call wrap_query/1 on the given cache, if implemented.
Types
@opaque presence()
Represents a presence as received from Discord. See Presence Update.
Callbacks
@callback bulk_create(Nostrum.Struct.Guild.id(), [presence()]) :: :ok
Bulk create multiple presences for the given guild in the cache.
@callback child_spec(term()) :: Supervisor.child_spec()
Retrieve the child specification for starting this mapping under a supervisor.
@callback create(presence()) :: :ok
Create a presence in the cache.
@callback get(Nostrum.Struct.Guild.id(), Nostrum.Struct.User.id()) :: {:ok, presence()} | {:error, any()}
@callback update(map()) :: {Nostrum.Struct.Guild.id(), old_presence :: presence() | nil, new_presence :: presence()} | :noop
Update the given presence in the cache from upstream data.
Return value
Return the guild ID along with the old presence (if it was cached, otherwise
nil) and the updated presence structure. If the :activities or :status
fields of the presence did not change, return :noop.
@callback wrap_query((-> result)) :: result when result: term()
A function that should wrap any :qlc operations.
If you implement a cache that is backed by a database and want to perform
cleanup and teardown actions such as opening and closing connections,
managing transactions and so on, you want to implement this function. nostrum
will then effectively call wrap_query(fn -> ... end).
If your cache does not need any wrapping, you can omit this.
Functions
@spec get(Nostrum.Struct.Guild.id(), Nostrum.Struct.User.id()) :: {:ok, presence()} | {:error, any()}
Retrieves a presence for a user from the cache by guild and id.
If successful, returns {:ok, presence}. Otherwise returns {:error, reason}.
Example
case Nostrum.Cache.PresenceCache.get(111133335555, 222244446666) do
{:ok, presence} ->
"They're #{presence.status}"
{:error, _reason} ->
"They're dead Jim"
end@spec get!(Nostrum.Struct.User.id(), Nostrum.Struct.Guild.id(), module()) :: presence() | no_return()
Same as get/1, but raise Nostrum.Error.CacheError in case of a failure.
Call wrap_query/1 on the given cache, if implemented.
If no cache is given, calls out to the default cache.