View Source Nostrum.Shard.Supervisor (Nostrum v0.10.0)

Supervises shard processes.

Implementation

As events are sent to the shard, the following happens:

  1. Shard looks to see what type of event it is, only dispatch events are sent to the producer.

  2. 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 the Map.key notation. 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.

  3. The payload is then written to the cache. To make sure we're not overrunning the cache, especially at startup with request_guild_members or other heavy payloads, this is done in the shard itself.

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

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

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

Link to this function

connect(shard_num, total_shards)

View Source

Spawns a shard with the specified number and connects it to the discord gateway.

Link to this function

disconnect(shard_num)

View Source (since 0.10.0)
@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, ...}
Link to this function

reconnect(opts)

View Source (since 0.10.0)

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)
Link to this function

update_status(status, game, stream, type)

View Source
Link to this function

update_voice_state(guild_id, channel_id, self_mute, self_deaf)

View Source