View Source Nostrum.Cache.MemberCache behaviour (Nostrum v0.7.0-rc1)
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.
See the documentation for the Nostrum.Cache.GuildCache
module for more
details on how to implement your own.
Link to this section Summary
Callbacks
Bulk create multiple members in the cache from upstream data.
Get all members cached for the given user ID.
Add the member for the given guild from upstream data.
Remove the given user for the given guild.
Get members for a given guild ID.
Get a single member on the given guild ID.
Return a query handle for usage with :qlc
.
Update the given member for the given guild from upstream data.
Functions
Return an enumerable of members with their users.
Link to this section Callbacks
@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.
@callback by_user(Nostrum.Struct.Guild.Member.user_id()) :: Enumerable.t({Nostrum.Struct.Guild.id(), Nostrum.Struct.Guild.Member.t()})
Get 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}
.
The result is returned as a stream.
@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.
@callback delete(Nostrum.Struct.Guild.id(), user :: map()) :: {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
.
@callback get(Nostrum.Struct.Guild.id()) :: Enumerable.t(Nostrum.Struct.Guild.Member.t())
Get members for a given guild ID.
The result is returned as a stream to accomodate for large guilds.
@callback get(Nostrum.Struct.Guild.id(), Nostrum.Struct.Guild.Member.user_id()) :: {:ok, Nostrum.Struct.Guild.Member.t()} | {:error, atom()}
Get a single member on the given guild ID.
The result should be returned as a stream to accomodate for large guilds.
@callback qlc_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 {guild_id, user_id, member}
, where:
guild_id
is aNostrum.Struct.Guild.id/0
,user_id
is aNostrum.Struct.User.id/0
, andmember
is aNostrum.Struct.Guild.Member.t/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 section Functions
@spec get_with_users(Nostrum.Struct.Guild.id()) :: Enumerable.t({Nostrum.Struct.Guild.Member.t(), Nostrum.Struct.User.t()})
Return an enumerable of members with their users.
parameters
Parameters
guild_id
(Nostrum.Struct.Guild.id/0
): The guild for which to return members.
return-value
Return value
Returns an enumerable that can be consumed with any function in the Stream
or Enumerable
module.
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.