View Source Nostrum.Cache.MessageCache behaviour (Nostrum v0.10.0)
Cache behaviour & dispatcher for Discord messages.
By default, Elixir.Nostrum.Cache.MessageCache.Noop will be used for caching
messages. You can override this in the :caches
option of the nostrum
application by setting the :messages
field to a different module, or
to the tuple {module, config}
where module
is the module to use and
config
is any compile-time configuration to pass to the module.
Unlike the other caches, the default is a no-op cache, as messages take
up a lot of memory and most bots do not need messages to be cached.
If you would like to cache messages, you can change the cache implementation
to one of the provided modules under Nostrum.Cache.MessageCache
or write your own.
Writing your own message cache
As with the other caches, the message cache API consists of two parts:
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.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
Used to constrain the return values of functions that can return a list of messages from the cache.
Callbacks
Deletes multiple messages from the cache, any message IDs given will always be for the same channel.
Called when a channel is deleted.
Retrieve the child spec for starting the cache under a supervisor.
Creates a message in the cache.
Deletes a message from the cache.
Retrieve a single Nostrum.Struct.Message
from the cache by its ID.
Return a QLC query handle for the cache for read operations.
Updates a message in the cache.
A function that should wrap any :qlc
operations.
Functions
Retrieve a message from the cache by channel and message id.
Retrieve a list of messages from the cache with a given author ID, optionally after a given date, and before a given date.
Retrieve a list of messages from the cache with a given channel ID, after a given date, and before a given date.
Retrieve a list of messages from the cache with a given channel ID and author ID, optionally after a given date, and before a given date.
Return the QLC handle of the configured cache.
Call wrap_qlc/1
on the given cache, if implemented.
Types
@type timestamp_like() :: Nostrum.Snowflake.t() | DateTime.t()
Used to constrain the return values of functions that can return a list of messages from the cache.
Callbacks
@callback bulk_delete(Nostrum.Struct.Channel.id(), [Nostrum.Struct.Message.id()]) :: [ Nostrum.Struct.Message.t() ]
Deletes multiple messages from the cache, any message IDs given will always be for the same channel.
Returns a list of the deleted messages. Note that if a message was not found in the cache, it will not be included in the returned list.
@callback channel_delete(Nostrum.Struct.Channel.id()) :: :ok
Called when a channel is deleted.
Any messages in the cache for the channel should be removed.
@callback child_spec(term()) :: Supervisor.child_spec()
Retrieve the child spec for starting the cache under a supervisor.
This callback is optional, and if not implemented, the cache will not be started under a supervisor.
@callback create(map()) :: Nostrum.Struct.Message.t()
Creates a message in the cache.
The argument given is the raw message payload from Discord's gateway.
@callback delete(Nostrum.Struct.Channel.id(), Nostrum.Struct.Message.id()) :: Nostrum.Struct.Message.t() | nil
Deletes a message from the cache.
Expects the deleted message to be returned if it was found.
@callback get(Nostrum.Struct.Message.id()) :: {:ok, Nostrum.Struct.Message.t()} | {:error, :not_found}
Retrieve a single Nostrum.Struct.Message
from the cache by its ID.
@callback query_handle() :: :qlc.query_handle()
Return a QLC query handle for the cache for 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 {message_id, message}
, where:
message_id
is aNostrum.Struct.Message.id/0
message
is aNostrum.Struct.Message.t/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()) :: {old_message :: Nostrum.Struct.Message.t() | nil, updated_message :: Nostrum.Struct.Message.t()}
Updates a message in the cache.
The argument given is the raw message payload from Discord's gateway,
and the return value is a tuple of the updated message and the old message if
it was found in the cache, otherwise nil
.
@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.
Functions
Retrieve a message from the cache by channel and message id.
get_by_author(author_id, after_timestamp \\ 0, before_timestamp \\ :infinity, cache \\ Nostrum.Cache.MessageCache.Noop)
View Source (since 0.10.0)Retrieve a list of messages from the cache with a given author ID, optionally after a given date, and before a given date.
Integers are treated as snowflakes, and the atom :infinity
when given
as a before date will be treated as the maximum possible date.
get_by_channel(channel_id, after_timestamp \\ 0, before_timestamp \\ :infinity, cache \\ Nostrum.Cache.MessageCache.Noop)
View Source (since 0.10.0)Retrieve a list of messages from the cache with a given channel ID, after a given date, and before a given date.
Integers are treated as snowflakes, and the atom :infinity
when given
as a before date will be treated as the maximum possible date.
get_by_channel_and_author(channel_id, author_id, after_timestamp \\ 0, before_timestamp \\ :infinity, cache \\ Nostrum.Cache.MessageCache.Noop)
View Source (since 0.10.0)Retrieve a list of messages from the cache with a given channel ID and author ID, optionally after a given date, and before a given date.
Return the QLC handle of the configured cache.
wrap_qlc(cache \\ Nostrum.Cache.MessageCache.Noop, fun)
View Source (since 0.10.0)Call wrap_qlc/1
on the given cache, if implemented.
If no cache is given, calls out to the default cache.