View Source Nostrum.Cache.PresenceCache behaviour (Nostrum v0.10.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

As with the other caches, the presence cache API consists of two parts:

The functions that nostrum calls, such as create/1 or update/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 by Nostrum.Api instead.
the QLC query handle for read operations, c:query_handle/0, and
the child_spec/1 callback for starting the cache under a supervisor.

You need to implement both of them for nostrum to work with your custom cache.

Summary

Types

presence()

Represents a presence as received from Discord. See Presence Update.

Callbacks

bulk_create(id, list)

Bulk create multiple presences for the given guild in the cache.

child_spec(term)

Retrieve the child specification for starting this mapping under a supervisor.

create(presence)

Create a presence in the cache.

get(id, id)

update(map)

Update the given presence in the cache from upstream data.

wrap_query(function)

A function that should wrap any :qlc operations.

Functions

get(guild_id, user_id)

Retrieves a presence for a user from the cache by guild and id.

get!(guild_id, user_id, cache \\ Nostrum.Cache.PresenceCache.ETS)

Same as get/1, but raise Nostrum.Error.CacheError in case of a failure.

wrap_query(cache \\ Nostrum.Cache.PresenceCache.ETS, fun)

Call wrap_query/1 on the given cache, if implemented.

Types

presence()

(since 0.5.0)

@opaque presence()

Represents a presence as received from Discord. See Presence Update.

Callbacks

bulk_create(id, list)

(since 0.5.0)

@callback bulk_create(Nostrum.Struct.Guild.id(), [presence()]) :: :ok

Bulk create multiple presences for the given guild in the cache.

child_spec(term)

(since 0.5.0)

@callback child_spec(term()) :: Supervisor.child_spec()

Retrieve the child specification for starting this mapping under a supervisor.

create(presence)

(since 0.5.0)

@callback create(presence()) :: :ok

Create a presence in the cache.

get(id, id)

(since 0.5.0)

@callback get(Nostrum.Struct.Guild.id(), Nostrum.Struct.User.id()) ::
  {:ok, presence()} | {:error, any()}

update(map)

(since 0.5.0)

@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.

wrap_query(function)

(optional) (since 0.8.0)

@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

get(guild_id, user_id)

(since 0.5.0)

@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

get!(guild_id, user_id, cache \\ Nostrum.Cache.PresenceCache.ETS)

(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.

wrap_query(cache \\ Nostrum.Cache.PresenceCache.ETS, fun)

(since 0.8.0)

@spec wrap_query(module(), (-> result)) :: result when result: term()

Call wrap_query/1 on the given cache, if implemented.

If no cache is given, calls out to the default cache.