shard

Documentation

Index

• func CloseShards(shards []ShardState) error
• func NewGatewayShard(m *Manager, id *gateway.Identifier) *gateway.Gateway
• func OpenShards(ctx context.Context, shards []ShardState) error
• type Manager
  • func NewIdentifiedManager(data gateway.IdentifyData, fn NewShardFunc) (*Manager, error)
  • func NewIdentifiedManagerWithURL(url string, id *gateway.Identifier, fn NewShardFunc) (*Manager, error)
  • func NewManager(token string, fn NewShardFunc) (*Manager, error)
  • func (m *Manager) Close() error
  • func (m *Manager) ForEach(f func(shard Shard))
  • func (m *Manager) FromGuildID(guildID discord.GuildID) (shard Shard, ix int)
  • func (m *Manager) GatewayURL() string
  • func (m *Manager) NumShards() int
  • func (m *Manager) Open(ctx context.Context) error
  • func (m *Manager) Rescale()
  • func (m *Manager) Shard(ix int) Shard
• type NewShardFunc
• type Shard
• type ShardState
  • func (state ShardState) ShardID() int

Functions

func CloseShards

func CloseShards(shards []ShardState) error

CloseShards closes the gateways of the given list of shard states.

func NewGatewayShard

func NewGatewayShard(m *Manager, id *gateway.Identifier) *gateway.Gateway

NewGatewayShard creates a new gateway that's plugged into the shard manager.

func OpenShards

func OpenShards(ctx context.Context, shards []ShardState) error

OpenShards opens the gateways of the given list of shard states.

Types

type Manager

type Manager struct {
	// contains filtered or unexported fields
}

Manager is the manager responsible for handling all sharding on this instance. An instance of Manager must never be copied.

func NewIdentifiedManager

func NewIdentifiedManager(data gateway.IdentifyData, fn NewShardFunc) (*Manager, error)

NewIdentifiedManager creates a new Manager using the given gateway.Identifier. The total number of shards will be taken from the identifier instead of being queried from Discord, but the shard ID will be ignored.

This function should rarely be used, since the shard information will be queried from Discord if it's required to shard anyway.

func NewIdentifiedManagerWithURL

func NewIdentifiedManagerWithURL(
	url string, id *gateway.Identifier, fn NewShardFunc) (*Manager, error)

NewIdentifiedManagerWithURL creates a new Manager with the given Identifier and gateway URL. It behaves similarly to NewIdentifiedManager.

func NewManager

func NewManager(token string, fn NewShardFunc) (*Manager, error)

NewManager creates a Manager using as many gateways as recommended by Discord.

func (*Manager) Close

func (m *Manager) Close() error

Close closes all gateways handled by this Manager; it will stop rescaling if the manager is currently being rescaled. If an error occurs, Close will attempt to close all remaining gateways first, before returning.

func (*Manager) ForEach

func (m *Manager) ForEach(f func(shard Shard))

ForEach calls the given function on each shard from first to last. The caller can safely access the number of shards by either asserting Shard to get the IdentifyData or call m.NumShards.

func (*Manager) FromGuildID

func (m *Manager) FromGuildID(guildID discord.GuildID) (shard Shard, ix int)

FromGuildID returns the Shard and the shard ID for the guild with the given ID.

func (*Manager) GatewayURL

func (m *Manager) GatewayURL() string

GatewayURL returns the URL to the gateway. The URL will always have the needed gateway parameters appended.

func (*Manager) NumShards

func (m *Manager) NumShards() int

NumShards returns the total number of shards. It is OK for the caller to rely on NumShards while they're inside ForEach.

func (*Manager) Open

func (m *Manager) Open(ctx context.Context) error

Open opens all gateways handled by this Manager. If an error occurs, Open will attempt to close all previously opened gateways before returning.

func (*Manager) Rescale

func (m *Manager) Rescale()

Rescale rescales the manager asynchronously. The caller MUST NOT call Rescale in the constructor function; doing so WILL cause the state to be inconsistent and eventually crash and burn and destroy us all.

func (*Manager) Shard

func (m *Manager) Shard(ix int) Shard

Shard gets the shard with the given ID.

type NewShardFunc

type NewShardFunc func(m *Manager, id *gateway.Identifier) (Shard, error)

NewShardFunc is the constructor to create a new gateway. For examples, see package session and state's. The constructor must manually connect the Manager's Rescale method appropriately.

A new Gateway must not open any background resources until OpenCtx is called; if the gateway has never been opened, its Close method will never be called. During callback, the Manager is not locked, so the callback can use Manager's methods without deadlocking.

var NewGatewayShardFunc NewShardFunc = func(m *Manager, id *gateway.Identifier) (Shard, error) {
	return NewGatewayShard(m, id), nil
}

NewGatewayShardFunc wraps around NewGatewayShard to be compatible with NewShardFunc.

type Shard

type Shard interface {
	Open(context.Context) error
	Close() error
}

Shard defines a shard gateway interface that the shard manager can use.

type ShardState

type ShardState struct {
	Shard Shard
	// This is a bit wasteful: 2 constant pointers are stored here, and they
	// waste GC cycles. This is unavoidable, however, since the API has to take
	// in a pointer to Identifier, not IdentifyData. This is to ensure rescales
	// are consistent.
	ID     gateway.Identifier
	Opened bool
}

ShardState wraps around the Gateway interface to provide additional state.

func (ShardState) ShardID

func (state ShardState) ShardID() int

ShardID returns the shard state's shard ID.