Expand description

Utilities for managing collections of shards.

Multiple shards may easily be created at once, with a per shard config created from a Fn(ShardId, ConfigBuilder) -> Config closure, with the help of the create_ set of functions. These functions will reuse shards’ TLS context and session queue, something otherwise achieved by cloning an existing Config.


Multiple shards’ events or websocket messages may be concurrently streamed via ShardEventStream or ShardMessageStream respectively, returning a mutable reference to the yielded shard and its item. The yielded shard is later returned to the stream in its Drop implementation. The streams are currently implemented via the futures::stream::FuturesUnordered type.

This is the recommended way to run multiple shards.


A multi-threaded executor is able to run tasks in parallel, but splitting shards across tasks requires channels to communicate between them, for example, to coordinate shutdowns. It is therefore not recommended unless required for performance reasons (a single core should, on a reasonably performant CPU, be capable of handling tens of thousands of Discord events per second).

See the gateway-parallel example for how to implement this.


Stream selecting the next gateway event from a collection of shards.
Stream selecting the next websocket message from a collection of shards.
Guard dereferencing to the shard that produced an event or message.
Failure when fetching the recommended number of shards to use from Discord’s REST API.


Type of StartRecommendedError that occurred.


Create a single bucket’s worth of shards.
Create a range of shards.
Create a range of shards from Discord’s recommendation.