View Source Nostrum.Cache.PresenceCache behaviour (Nostrum v0.6.1)

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 the user calls, currently only get/2.

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

You need to implement both of them for nostrum to work with your custom cache. You also need to implement Supervisor callbacks, which will start your cache as a child under Nostrum.Cache.CacheSupervisor: As an example, the Nostrum.Cache.PresenceCache.ETS implementation uses this to to set up its ETS table it uses for caching. See the callbacks section for every nostrum-related callback you need to implement.

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.

Create a presence in the cache.

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

Update the given presence in the cache from upstream data.

Link to this section Types

Link to this opaque

presence()

View Source (opaque) (since 0.5.0)

Specs

presence()

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

Link to this section Callbacks

Specs

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

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

Specs

create(presence()) :: :ok

Create a presence in the cache.

Specs

get(Nostrum.Struct.User.id(), Nostrum.Struct.Guild.id()) ::
  {: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

case Nostrum.Cache.PresenceCache.get(111133335555, 222244446666) do
  {:ok, presence} ->
    "They're #{presence.status}"
  {:error, _reason} ->
    "They're dead Jim"
end

Specs

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.

Link to this section Functions