View Source Nostrum.Cache.UserCache behaviour (Nostrum v0.10.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_create(user_payloads)

Bulk add multiple users to the cache at once.

child_spec(term)

Retrieve the child specification for starting this mapping under a supervisor.

create(payload)

Add a new user to the cache based on the Discord Gateway payload.

delete(snowflake)

Delete a user by ID.

get(id)

Retrieve a user from the cache by id.

update(payload)

Update a user in the cache based on payload sent via the Gateway.

wrap_query(function)

A function that should wrap any :qlc operations.

Functions

get(id)

Retrieve a user from the cache by ID.

get!(id)

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

wrap_query(cache \\ Nostrum.Cache.UserCache.ETS, fun)

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

Callbacks

bulk_create(user_payloads)

@callback bulk_create(user_payloads :: Enum.t()) :: :ok

Bulk add multiple users to the cache at once.

Returns :ok.

child_spec(term)

@callback child_spec(term()) :: Supervisor.child_spec()

Retrieve the child specification for starting this mapping under a supervisor.

create(payload)

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

delete(snowflake)

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

get(id)

@callback get(Nostrum.Struct.User.id()) ::
  {:ok, Nostrum.Struct.User.t()} | {:error, atom()}

Retrieve a user from the cache by id.

update(payload)

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

wrap_query(function)

(optional) (since 0.8.0)

@callback wrap_query((-> 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_query(fn -> ... end).

If your cache does not need any wrapping, you can omit this.

Functions

get(id)

@spec get(Nostrum.Struct.User.id()) ::
  {:ok, Nostrum.Struct.User.t()} | {:error, atom()}

Retrieve a user from the cache by ID.

Example

case Nostrum.Cache.UserCache.get(1111222233334444) do
  {:ok, user} ->
    "We found " <> user.username
  {:error, _reason} ->
    "No es bueno"
end

get!(id)

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

wrap_query(cache \\ Nostrum.Cache.UserCache.ETS, fun)

(since 0.8.0)

@spec wrap_query(module(), (-> result)) :: result when result: term()

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

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