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

Link to this type

timestamp_like()

View Source (since 0.10.0)
@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

Link to this callback

bulk_delete(id, list)

View Source (since 0.10.0)

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.

Link to this callback

channel_delete(id)

View Source (since 0.10.0)
@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.

Link to this callback

child_spec(term)

View Source (since 0.10.0)
@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.

Link to this callback

create(map)

View Source (since 0.10.0)
@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.

Link to this callback

delete(id, id)

View Source (since 0.10.0)

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.

Link to this callback

query_handle()

View Source (since 0.10.0)
@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:

If your cache needs some form of setup or teardown for QLC queries (such as opening connections), see wrap_qlc/1.

Link to this callback

update(map)

View Source (since 0.10.0)
@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.

Link to this callback

wrap_qlc(function)

View Source (optional) (since 0.10.0)
@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

Link to this function

get(message_id)

View Source (since 0.10.0)

Retrieve a message from the cache by channel and message id.

Link to this function

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.

Link to this function

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.

Link to this function

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.

Link to this function

query_handle()

View Source (since 0.10.0)

Return the QLC handle of the configured cache.

Link to this function

wrap_qlc(cache \\ Nostrum.Cache.MessageCache.Noop, fun)

View Source (since 0.10.0)
@spec wrap_qlc(module(), (-> result)) :: result when result: term()

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

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