View Source Nostrum.Cache.UserCache behaviour (Nostrum v0.9.0)
Cache behaviour & dispatcher for users.
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.UserCache.ETS will be used for caching users.
You can override this in the :caches option of the :nostrum application
by setting the :users field to a different module implementing the behaviour
defined by this module.
See the documentation for the Nostrum.Cache.GuildCache module for more details.
Summary
Callbacks
Bulk add multiple users to the cache at once.
Retrieve the child specification for starting this mapping under a supervisor.
Add a new user to the cache based on the Discord Gateway payload.
Delete a user by ID.
Return a query handle for usage with :qlc.
Update a user in the cache based on payload sent via the Gateway.
A function that should wrap any :qlc operations.
Functions
Retrieves a user from the cache by id.
Same as get/1, but raises Nostrum.Error.CacheError in case of a failure.
Call query_handle/0 on the configured cache.
Call wrap_qlc/1 on the given cache, if implemented.
Callbacks
@callback bulk_create(user_payloads :: Enum.t()) :: :ok
Bulk add multiple users to the cache at once.
Returns :ok.
@callback child_spec(term()) :: Supervisor.child_spec()
Retrieve the child specification for starting this mapping under a supervisor.
@callback create(payload :: map()) :: Nostrum.Struct.User.t()
Add a new user to the cache based on the Discord Gateway payload.
Returns a Nostrum.Struct.User.t/0 struct representing the created user.
@callback delete(snowflake :: Nostrum.Struct.User.id()) :: :noop | Nostrum.Struct.User.t()
Delete a user by ID.
Returns the deleted user if present in the cache, or
:noop if the user was not cached.
@callback query_handle() :: :qlc.query_handle()
Return a query handle for usage with :qlc.
This is used by nostrum to provide automatic joins between the member and the user cache, and may be used for other functions in the future.
The Erlang manual on Implementing a QLC Table contains examples for implementation.
The query handle must return items in the form {user_id, user}, where
user_id is a Nostrum.Struct.User.id/0 and user is a
Nostrum.Struct.User.t/0.
@callback update(payload :: map()) :: {Nostrum.Struct.User.t() | nil, Nostrum.Struct.User.t()}
Update a user in the cache based on payload sent via the Gateway.
Returns :noop if the user has not been updated in the cache, or
{old_user, new_user} is the user has been written to the cache.
@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
@spec get(Nostrum.Struct.User.id(), module()) :: {:ok, Nostrum.Struct.User.t()} | {:error, atom()}
Retrieves a user from the cache by id.
This function can be called with the cache to use as an optional argument. By default, the cache configured at compile time is used.
Example
case Nostrum.Cache.UserCache.get(1111222233334444) do
{:ok, user} ->
"We found " <> user.username
{:error, _reason} ->
"No es bueno"
end@spec get!(Nostrum.Struct.User.id()) :: no_return() | Nostrum.Struct.User.t()
Same as get/1, but raises Nostrum.Error.CacheError in case of a failure.
@spec query_handle() :: :qlc.query_handle()
Call query_handle/0 on the configured cache.
Call wrap_qlc/1 on the given cache, if implemented.
If no cache is given, calls out to the default cache.