Nostrum

View Source Nostrum.Cache.MemberCache behaviour (Nostrum v0.8.0)

Cache behaviour & dispatcher for guild members.

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.MemberCache.ETS will be used for caching members. You can override this in the :caches option of the :nostrum application by setting the :members field to a different module implementing the behaviour defined by this module.

The user-facing functions of this module can be called with a custom cache as the final argument. This is mainly useful if you want to test the cache: by default, nostrum will use Elixir.Nostrum.Cache.MemberCache.ETS.

Link to this section Summary

Callbacks

bulk_create(id, members)

Bulk create multiple members in the cache from upstream data.

child_spec(term)

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

create(id, member)

Add the member for the given guild from upstream data.

delete(id, user_id)

Remove the given user for the given guild.

query_handle()

Return a QLC query handle for cache read operations.

update(id, member)

Update the given member for the given guild from upstream data.

wrap_qlc(function)

A function that should wrap any :qlc operations.

Functions

fold(acc, guild_id, member_reducer, cache \\ Nostrum.Cache.MemberCache.ETS)

Fold (reduce) over members for the given guild ID.

fold_by_user(acc, user_id, member_reducer, cache \\ Nostrum.Cache.MemberCache.ETS)

Reduce over all members cached for the given user ID.

fold_with_users(acc, guild_id, fun, cache \\ Nostrum.Cache.MemberCache.ETS)

Calls fun on each member and its user on the given guild ID, with the given accumulator.

get(guild_id, user_id, cache \\ Nostrum.Cache.MemberCache.ETS)

Get a single member on the given guild ID.

get_with_user(guild_id, member_id, cache \\ Nostrum.Cache.MemberCache.ETS)

Return a member together with its user via the user cache.

query_handle()

Return the QLC handle of the configured cache.

wrap_qlc(cache \\ Nostrum.Cache.MemberCache.ETS, fun)

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

Link to this section Callbacks

Link to this callback

bulk_create(id, members)

View Source (since 0.7.0) 
@callback bulk_create(Nostrum.Struct.Guild.id(), members :: [member :: map()]) :: true

Bulk create multiple members in the cache from upstream data.

Return value is unused, as we currently do not dispatch a gateway for this.

Link to this callback

child_spec(term)

View Source (since 0.7.0) 
@callback child_spec(term()) :: Supervisor.child_spec()

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

Link to this callback

create(id, member)

View Source (since 0.7.0) 
@callback create(Nostrum.Struct.Guild.id(), member :: map()) ::
  Nostrum.Struct.Guild.Member.t()

Add the member for the given guild from upstream data.

Return the casted member structure.

Link to this callback

delete(id, user_id)

View Source (since 0.7.0) 
@callback delete(Nostrum.Struct.Guild.id(), Nostrum.Struct.Guild.Member.user_id()) ::
  {Nostrum.Struct.Guild.id(), old_member :: Nostrum.Struct.Guild.Member.t()}
  | :noop

Remove the given user for the given guild.

Return the guild ID and old member if the member was cached. Otherwise, return :noop.

Link to this callback

query_handle()

View Source (since 0.7.0) 
@callback query_handle() :: :qlc.query_handle()

Return a QLC query handle for cache 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 {guild_id, user_id, member}, 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(id, member)

View Source (since 0.7.0) 
@callback update(Nostrum.Struct.Guild.id(), member :: map()) ::
  {Nostrum.Struct.Guild.id(),
   old_member :: Nostrum.Struct.Guild.Member.t() | nil,
   updated_member :: Nostrum.Struct.Guild.Member.t()}

Update the given member for the given guild from upstream data.

Return the guild ID that was updated, the old cached member (if the member was known to the cache), and the updated member.

note-regarding-intents

 Note regarding intents

Even if the required intents to receive GUILD_MEMBER_UPDATE events are disabled to a point where we do not receive guild creation events, it is still possible to receive the event for our own user. An example of this can be found in issue #293. Note that the issue predates the modern nostrum caching infrastructure.

Link to this callback

wrap_qlc(function)

View Source (optional) (since 0.8.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.

Link to this section Functions

Link to this function

fold(acc, guild_id, member_reducer, cache \\ Nostrum.Cache.MemberCache.ETS)

View Source (since 0.8.0) 
@spec fold(
  acc,
  Nostrum.Struct.Guild.id(),
  (Nostrum.Struct.Guild.Member.t(), acc -> acc),
  module()
) ::
  acc
when acc: term()

Fold (reduce) over members for the given guild ID.

parameters

 Parameters

  • acc: The initial accumulator. Also returned if no guild members were found.
  • guild_id: The guild for which to reduce members.
  • fun: Called for every element in the result. Takes a pair in the form {member, acc), and must return the updated accumulator.

return-value

 Return value

Returns the resulting accumulator via fun. Returns acc unchanged if no results were found.

Link to this function

fold_by_user(acc, user_id, member_reducer, cache \\ Nostrum.Cache.MemberCache.ETS)

View Source (since 0.8.0) 
@spec fold_by_user(
  acc,
  Nostrum.Struct.Guild.Member.user_id(),
  ({Nostrum.Struct.Guild.id(), Nostrum.Struct.Guild.Member.t()}, acc -> acc),
  module()
) :: acc
when acc: term()

Reduce over all members cached for the given user ID.

The members will be returned alongside their guild ID as a pair in the format {guild_id, member}.

Link to this function

fold_with_users(acc, guild_id, fun, cache \\ Nostrum.Cache.MemberCache.ETS)

View Source (since 0.8.0) 
@spec fold_with_users(
  acc,
  Nostrum.Struct.Guild.id(),
  ({Nostrum.Struct.Guild.Member.t(), Nostrum.Struct.User.t()}, acc -> acc),
  module()
) :: acc
when acc: term()

Calls fun on each member and its user on the given guild ID, with the given accumulator.

parameters

 Parameters

  • acc (term()): The initial accumulator. Also returned if no guild members were found.
  • guild_id (Nostrum.Struct.Guild.id/0): The guild for which to reduce members.
  • fun (function()): Called for every element in the result. Takes a pair in the form {{member, user}, acc), and must return the updated accumulator.

return-value

 Return value

Returns the resulting accumulator via fun. Returns acc unchanged if no results were found.

If the user for a guild member is not found, the member and user won't be present in the result. Barring a bug in nostrum's caching, this should never happen in practice.

Link to this function

get(guild_id, user_id, cache \\ Nostrum.Cache.MemberCache.ETS)

View Source (since 0.7.0) 
@spec get(Nostrum.Struct.Guild.id(), Nostrum.Struct.Guild.Member.user_id(), module()) ::
  {:ok, Nostrum.Struct.Guild.Member.t()} | {:error, atom()}

Get a single member on the given guild ID.

Link to this function

get_with_user(guild_id, member_id, cache \\ Nostrum.Cache.MemberCache.ETS)

View Source (since 0.7.0) 
@spec get_with_user(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.Guild.Member.user_id(),
  module()
) ::
  {Nostrum.Struct.Guild.Member.t(), Nostrum.Struct.User.t() | nil} | nil

Return a member together with its user via the user cache.

Link to this function

query_handle()

View Source (since 0.8.0)

Return the QLC handle of the configured cache.

Link to this function

wrap_qlc(cache \\ Nostrum.Cache.MemberCache.ETS, fun)

View Source (since 0.8.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.