View Source Nostrum.Shard.Supervisor (Nostrum v0.10.0)
Supervises shard processes.
Implementation
As events are sent to the shard, the following happens:
Shard looks to see what type of event it is, only dispatch events are sent to the producer.
If the event is a
Dispatch, the payload is converted to an atom-keyed map. This is done because over ETF (which Nostrum uses), map keys are sometimes binaries and sometimes strings, making it a real headache. Additionally, with atom keys, we can use theMap.keynotation. This is normally considered unsafe but a debug messages will be emitted if a key is unsafely converted to an atom. In this way we can ensure that our atom table is not growing unbounded.The payload is then written to the cache. To make sure we're not overrunning the cache, especially at startup with
request_guild_membersor other heavy payloads, this is done in the shard itself.The cache updates itself from the new data. In some cases, such as update or delete events, it may send out a second "old" object as well, that helps the library user to determine what changed.
After writing to the cache, the shard
sends out the event after going through the cache to all subscribed processes. In general, the payload will often match the payload described by the official Discord API documentation.The shard instructs the websocket client that it's ready to read more data. This prevents flooding the shard with messages that it may not be able to handle yet, thus growing the message queue and the memory usage.
Summary
Types
Represents gateway resume information.
Shard number(shard_id). Range is 0..total_shards-1.
Total shard count(num_shards).
Functions
Returns a specification to start this module under a supervisor.
Spawns a shard with the specified number and connects it to the discord gateway.
Disconnects the shard with the given shard number from the Gateway.
Reconnect to the gateway using the provided resume_information/0.
Types
@type resume_information() :: %{ shard_num: shard_num(), total_shards: total_shards(), gateway: String.t(), resume_gateway: String.t() | nil, session: String.t(), seq: pos_integer() }
Represents gateway resume information.
@type shard_num() :: non_neg_integer()
Shard number(shard_id). Range is 0..total_shards-1.
@type total_shards() :: pos_integer()
Total shard count(num_shards).
Functions
Returns a specification to start this module under a supervisor.
See Supervisor.
@spec connect(shard_num(), total_shards()) :: DynamicSupervisor.on_start_child()
Spawns a shard with the specified number and connects it to the discord gateway.
@spec disconnect(shard_num()) :: resume_information()
Disconnects the shard with the given shard number from the Gateway.
This function returns resume_information/0 which can be provided
to reconnect/1 to reconnect a shard to the gateway and (attempt) to
catch up on any missed events.
Examples
iex> Nostrum.Shard.Supervisor.disconnect(4)
%{shard_num: 4, ...}@spec reconnect(resume_information()) :: DynamicSupervisor.on_start_child()
Reconnect to the gateway using the provided resume_information/0.
Resuming is performed by the gateway on a best effort basis, it is not guaranteed that a resume will work (though Nostrum will handle failed attempts at a resumption). If a reconnect is successful, any events received during the reconnection period should be received. If the reconnect fails, events received between the disconnect and re-authentication may be lost.
For more information about resuming sessions, visit the Discord Developer Portal.
Examples
iex> resume = Nostrum.Shard.Supervisor.disconnect(4)
%{shard_num: 4, ...}
iex> Nostrum.Shard.Supervisor.reconnect(resume)