View Source Nostrum.Cache.GuildCache behaviour (Nostrum v0.7.0)
Cache behaviour & dispatcher for guilds.
You can call the functions provided by this module independent of which cache is configured, and it will dispatch to the configured cache implementation.
By default, Elixir.Nostrum.Cache.GuildCache.ETS will be used for caching guilds.
You can override this in the :caches
option of the :nostrum
application
by setting the :guilds
field to a different module implementing the
Nostrum.Cache.GuildCache
behaviour. Any module below
Nostrum.Cache.GuildCache
can be used as a cache.
writing-your-own-guild-cache
Writing your own guild cache
As with the other caches, the guild cache API consists of two parts:
The functions that the user calls, such as
all/0
orselect_by/2
.The functions that nostrum calls, such as
create/1
orupdate/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.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.GuildCache.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.
Note that this module also defines a few helper functions, such as get!/1
or select_by!/2
, which call the backing cache's regular functions and
perform the result unwrapping by themselves.
The "upstream data" wording in this module references the fact that the data that the guild 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
A clause for filtering guilds.
Specifies the reason for why a lookup operation has failed.
A selector for looking up entries in the cache.
Callbacks
Retrieves all Nostrum.Struct.Guild
from the cache.
Create a channel for the guild from upstream data.
Delete the given channel from the guild.
Update the given channel on the given guild from upstream data.
Create a guild in the cache.
Delete a guild from the cache.
Update the emoji list of the given guild from upstream data.
Retrieves a single Nostrum.Struct.Guild
from the cache via its id
.
Retrieves a single Nostrum.Struct.Guild
where it matches the clauses
.
Decrement the member count for this guild by one.
Increment the member count for this guild by one.
Create a role on the given guild from upstream data.
Delete the given role on the given guild.
Update a role on the given guild from upstream data.
Selects values using a selector
from a Nostrum.Struct.Guild
.
Selects guilds matching selector
from all Nostrum.Struct.Guild
in the cache.
Selects values using a selector
from a Nostrum.Struct.Guild
that matches
the clauses
.
Update a guild from upstream data.
Update the voice state of the given guild from upstream data.
Functions
Same as get/1
, but raises Nostrum.Error.CacheError
in case of failure.
Same as get_by/1
, but raises Nostrum.Error.CacheError
in case of failure.
Same as select/2
, but raises Nostrum.Error.CacheError
in case of failure.
Same as select_by/2
, but raises Nostrum.Error.CacheError
in case of failure.
Link to this section Types
@type clause() :: {:id, Nostrum.Struct.Guild.id()} | {:channel_id, Nostrum.Struct.Channel.id()} | {:message, Nostrum.Struct.Message.t()}
A clause for filtering guilds.
A collection of clause/0
s for filtering guilds.
@type reason() :: :id_not_found | :id_not_found_on_guild_lookup
Specifies the reason for why a lookup operation has failed.
@type selector() :: (Nostrum.Struct.Guild.t() -> any())
A selector for looking up entries in the cache.
Link to this section Callbacks
@callback all() :: Enum.t()
Retrieves all Nostrum.Struct.Guild
from the cache.
@callback channel_create(Nostrum.Struct.Guild.id(), channel :: map()) :: Nostrum.Struct.Channel.t()
Create a channel for the guild from upstream data.
Return the adapted Nostrum.Struct.Channel.t/0
structure.
@callback channel_delete(Nostrum.Struct.Guild.id(), Nostrum.Struct.Channel.id()) :: Nostrum.Struct.Channel.t() | :noop
Delete the given channel from the guild.
If the channel was cached, return the original channel. Return :noop
otherwise.
@callback channel_update(Nostrum.Struct.Guild.id(), channel :: map()) :: {old_channel :: Nostrum.Struct.Channel.t(), new_channel :: Nostrum.Struct.Channel.t()}
Update the given channel on the given guild from upstream data.
Return the original channel before the update, and the updated channel.
@callback create(Nostrum.Struct.Guild.t()) :: true
Create a guild in the cache.
@callback delete(Nostrum.Struct.Guild.id()) :: Nostrum.Struct.Guild.t() | nil
Delete a guild from the cache.
Return the old guild if it was cached, or nil
otherwise.
@callback emoji_update(Nostrum.Struct.Guild.id(), emojis :: [map()]) :: {old_emojis :: [Nostrum.Struct.Emoji.t()], new_emojis :: [Nostrum.Struct.Emoji.t()]}
Update the emoji list of the given guild from upstream data.
Discord sends us the complete emoji list on an update, which is passed here.
Return the old list of emojis before the update, and the updated list of emojis.
@callback get(Nostrum.Struct.Guild.id()) :: {:ok, Nostrum.Struct.Guild.t()} | {:error, reason()}
Retrieves a single Nostrum.Struct.Guild
from the cache via its id
.
Returns {:error, reason}
if no result was found.
examples
Examples
iex> Nostrum.Cache.GuildCache.get(0)
{:ok, %Nostrum.Struct.Guild{id: 0}}
iex> Nostrum.Cache.GuildCache.get(10)
{:error, :id_not_found_on_guild_lookup}
@callback get_by(clauses()) :: {:ok, Nostrum.Struct.Guild.t()} | {:error, reason()}
Retrieves a single Nostrum.Struct.Guild
where it matches the clauses
.
Returns {:error, reason}
if no result was found.
iex> Nostrum.Cache.GuildCache.get_by(id: 0)
{:ok, %Nostrum.Struct.Guild{id: 0}}
iex> Nostrum.Cache.GuildCache.get_by(%{id: 0})
{:ok, %Nostrum.Struct.Guild{id: 0}}
iex> Nostrum.Cache.GuildCache.get_by(id: 10)
{:error, :id_not_found_on_guild_lookup}
@callback member_count_down(Nostrum.Struct.Guild.id()) :: true
Decrement the member count for this guild by one.
@callback member_count_up(Nostrum.Struct.Guild.id()) :: true
Increment the member count for this guild by one.
@callback role_create(Nostrum.Struct.Guild.id(), role :: map()) :: {Nostrum.Struct.Guild.id(), new_role :: Nostrum.Struct.Guild.Role.t()}
Create a role on the given guild from upstream data.
Return the casted role.
@callback role_delete(Nostrum.Struct.Guild.id(), Nostrum.Struct.Guild.Role.id()) :: {Nostrum.Struct.Guild.id(), old_role :: Nostrum.Struct.Guild.Role.t()} | :noop
Delete the given role on the given guild.
Return the guild and the old role if it was cached, or :noop
otherwise.
@callback role_update(Nostrum.Struct.Guild.id(), role :: map()) :: {Nostrum.Struct.Guild.id(), old_role :: Nostrum.Struct.Guild.Role.t(), new_role :: Nostrum.Struct.Guild.Role.t()}
Update a role on the given guild from upstream data.
Return the old role before the update and the updated role.
@callback select(Nostrum.Struct.Guild.id(), selector()) :: {:ok, any()} | {:error, reason()}
Selects values using a selector
from a Nostrum.Struct.Guild
.
Returns {:error, reason}
if no result was found.
examples
Examples
iex> Nostrum.Cache.GuildCache.select(0, fn guild -> guild.id end)
{:ok, 0}
iex> Nostrum.Cache.GuildCache.select(10, fn guild -> guild.id end)
{:error, :id_not_found_on_guild_lookup}
@callback select_all(selector :: (Nostrum.Struct.Guild.t() -> any())) :: Enum.t()
Selects guilds matching selector
from all Nostrum.Struct.Guild
in the cache.
Selects values using a selector
from a Nostrum.Struct.Guild
that matches
the clauses
.
Returns {:error, reason}
if no result was found.
iex> Nostrum.Cache.GuildCache.select_by([id: 0], fn guild -> guild.id end)
{:ok, 0}
iex> Nostrum.Cache.GuildCache.select_by(%{id: 0}, fn guild -> guild.id end)
{:ok, 0}
iex> Nostrum.Cache.GuildCache.select_by([id: 10], fn guild -> guild.id end)
{:error, :id_not_found_on_guild_lookup}
@callback update(map()) :: {old_guild :: Nostrum.Struct.Guild.t(), updated_guild :: Nostrum.Struct.Guild.t()}
Update a guild from upstream data.
Return the original guild before the update, and the updated guild.
@callback voice_state_update(Nostrum.Struct.Guild.id(), state :: map()) :: {Nostrum.Struct.Guild.id(), new_state :: [map()]}
Update the voice state of the given guild from upstream data.
Note that it is recommended to drop the :member
/ "member"
keys of
the supplied upstream data, as these would otherwise duplicate the data
that is being kept in the guild cache already.
Return the guild ID and the updated voice states of the guild.
Link to this section Functions
@spec get!(Nostrum.Struct.Guild.id()) :: Nostrum.Struct.Guild.t() | no_return()
Same as get/1
, but raises Nostrum.Error.CacheError
in case of failure.
@spec get_by!(clauses()) :: Nostrum.Struct.Guild.t() | no_return()
Same as get_by/1
, but raises Nostrum.Error.CacheError
in case of failure.
@spec select!(Nostrum.Struct.Guild.id(), selector()) :: any() | no_return()
Same as select/2
, but raises Nostrum.Error.CacheError
in case of failure.
Same as select_by/2
, but raises Nostrum.Error.CacheError
in case of failure.