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

Cache behaviour & dispatcher for channels.

You can call the functions provided by this module independent of which cache is configured, and it will dispatch to the configured cache implementation. The user-facing functions for reading the cache can be found in the "Reading the cache" section.

By default, Elixir.Nostrum.Cache.ChannelCache.ETS will be used for caching channels. You can override this in the :caches option of the :nostrum application by setting the :channels field to a different module implementing the Nostrum.Cache.ChannelCache behaviour. Any module below Nostrum.Cache.ChannelCache can be used as a cache.

Writing your own channel cache

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

  • The functions that the user calls, currently only get/1 and get!/1

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

The "upstream data" wording in this module references the fact that the data that the channel cache (and other caches) retrieves represents the raw data we receive from the upstream connection, no attempt is made by nostrum to sanitize the data before it enters the cache. Caching implementations need to cast the data to the resulting type themselves. A possible future improvement would be moving the data casting into this module before the backing cache implementation is called.

Link to this section Summary

Types

Specifies the reason for why a lookup operation has failed.

Callbacks

Create a channel in the cache.

Delete a channel from the cache.

Retrieves a channel from the cache.

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

Lookup a channel from the cache by ID.

Update a channel from upstream data.

Link to this section Types

Specs

reason() :: :channel_not_found

Specifies the reason for why a lookup operation has failed.

Link to this section Callbacks

Specs

create(map()) :: Nostrum.Struct.Channel.t()

Create a channel in the cache.

Specs

Delete a channel from the cache.

Return the old channel if it was cached, or nil otherwise.

Specs

get(Nostrum.Struct.Channel.id() | Nostrum.Struct.Message.t()) ::
  {:error, reason()} | {:ok, Nostrum.Struct.Channel.t()} | {:error, reason()}

Retrieves a channel from the cache.

Internally, the ChannelCache process only stores Nostrum.Struct.Channel.dm_channel/0 references. To get channel information, a call is made to a Nostrum.Cache.GuildCache.

If successful, returns {:ok, channel}. Otherwise, returns {:error, reason}

Example

case Nostrum.Cache.ChannelCache.get(133333333337) do
  {:ok, channel} ->
    "We found " <> channel.name
  {:error, _reason} ->
    "Donde esta"
end

Specs

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

Specs

lookup(Nostrum.Struct.Channel.id()) :: {:error, reason()} | {:ok, map()}

Lookup a channel from the cache by ID.

Return channel_not_found if not found.

Specs

Update a channel from upstream data.

Return the original channel before the update, and the updated channel.

Link to this section Functions