View Source Nostrum.Cache.PresenceCache behaviour (Nostrum v0.8.0)
Cache 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
Writing your own presence cache
As with the other caches, the presence cache API consists of two 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 QLC query handle for read operations,
query_handle/0, andthe
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.
Link to this section 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.
Return a QLC query handle for cache read operations.
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.
Return the QLC handle of the configured cache.
Call wrap_qlc/1 on the given cache, if implemented.
Link to this section Types
@opaque presence()
Represents a presence as received from Discord. See Presence Update.
Link to this section 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 query_handle() :: :qlc.query_handle()
Return a QLC query handle for cache read operations.
This is used by nostrum to provide any read operations on the cache. Write operations still need to be implemented separately.
The Erlang manual on Implementing a QLC
Table
contains examples for implementation. To prevent full table scans, accept
match specifications in your TraverseFun and implement a LookupFun as
documented.
The query handle must return items in the form {{guild_id, user_id}, presence}, where:
guild_idis aNostrum.Struct.Guild.id/0, anduser_idis aNostrum.Struct.User.id/0, andpresenceis apresence/0.
If your cache needs some form of setup or teardown for QLC queries (such as
opening connections), see wrap_qlc/1.
@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 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_qlc((() -> 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_qlc(fn -> :qlc.e(...) end).
If your cache does not need any wrapping, you can omit this.
Link to this section Functions
get(guild_id, user_id, cache \\ Nostrum.Cache.PresenceCache.ETS)
View Source (since 0.5.0)@spec get(Nostrum.Struct.Guild.id(), Nostrum.Struct.User.id(), module()) :: {:ok, presence()} | {:error, :presence_not_found}
Retrieves a presence for a user from the cache by guild and id.
If successful, returns {:ok, presence}. Otherwise returns {:error, reason}.
example
Example
case Nostrum.Cache.PresenceCache.get(111133335555, 222244446666) do
{:ok, presence} ->
"They're #{presence.status}"
{:error, _reason} ->
"They're dead Jim"
endget!(guild_id, user_id, cache \\ Nostrum.Cache.PresenceCache.ETS)
View Source (since 0.5.0)@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.
Return the QLC handle of the configured cache.
wrap_qlc(cache \\ Nostrum.Cache.PresenceCache.ETS, fun)
View Source (since 0.8.0)Call wrap_qlc/1 on the given cache, if implemented.
If no cache is given, calls out to the default cache.