Pool

Pool is the central connection manager. It holds all Node connections, handles reconnection, and routes players to the best available node via a penalty-based algorithm.

Guide

See the Node & Pool Guide for multi-node setup, failover, and caching.

---

Pool

The revvlink Pool represents a collection of :class:~revvlink.Node and helper methods for searching tracks.

To connect a :class:~revvlink.Node please use this Pool.

ℹNote

All methods and attributes on this class are class level, not instance. Do not create an instance of this class.

region_from_endpoint classmethod

region_from_endpoint(endpoint: str | None) -> str | None

Parses a Discord voice endpoint string to map it back to a Region name.

Parameters:

Name	Type	Description	Default
endpoint	str | None	The raw Discord voice endpoint (e.g., "us-east1.discord.gg:443").	required

Returns:

Type	Description
str | None	The region label string (e.g., "us", "eu", "asia"), or "global" if no match is found. Returns None if the endpoint is empty.

connect async classmethod

connect(
    *,
    nodes: Iterable[Node],
    client: Client | None = None,
    cache_capacity: int | None = None,
    regions: dict[str, list[str]] | None = None,
) -> dict[str, Node]

Connect the provided Iterable[:class:Node] to Lavalink.

Parameters:

Name	Type	Description	Default
nodes	Iterable[Node]	The :class:Node's to connect to Lavalink.	required
client	Client | None	The :class:discord.Client to use to connect the :class:Node. If the Node already has a client set, this method will not override it. Defaults to None.	None
cache_capacity	int | None	An optional integer of the amount of track searches to cache. This is an experimental mode. Passing None will disable this experiment. Defaults to None.	None
regions	dict[str, list[str]] | None	An optional mapping of region label to a list of Discord voice endpoint substrings (e.g. {"us": ["iad", "atl"], "eu": ["ams"]}). When provided, this overrides the built-in REGIONS map used by Pool.region_from_endpoint and Pool.get_node. Defaults to None, which keeps the built-in map.	None

Returns:

Type	Description
dict[str, :class:`Node`]	A mapping of :attr:Node.identifier to :class:Node associated with the :class:Pool.

Raises:

Type	Description
AuthorizationFailedException	The node password was incorrect.
InvalidClientException	The :class:discord.Client passed was not valid.
NodeException	The node failed to connect properly. Please check that your Lavalink version is version 4.The client parameter is no longer required.

reconnect async classmethod

reconnect() -> dict[str, Node]

Reconnect all nodes in the pool that are currently disconnected.

Returns:

Type	Description
dict[str, :class:`Node`]	The mapping of nodes in the pool.

close async classmethod

close() -> None

Close and clean up all :class:~revvlink.Node on this Pool.

This calls :meth:revvlink.Node.close on each node.

nodes

nodes() -> dict[str, Node]

A mapping of :attr:Node.identifier to :class:Node that have previously been successfully connected.

This property now returns a copy.

get_node classmethod

get_node(
    identifier: str | None = None,
    /,
    *,
    region: str | None = None,
) -> Node

Retrieve a :class:Node from the :class:Pool with the given identifier.

If no identifier is provided, this method returns the best node. If a region is provided, it tries to find the best node matching that region.

Parameters:

Name	Type	Description	Default
identifier	str | None	An optional identifier to retrieve a :class:Node.	None
region	str | None	An optional region string to filter nodes for load balancing.	None

Raises:

Type	Description
InvalidNodeException	Raised when a Node can not be found, or no :class:Node exists on the :class:Pool. The id parameter was changed to identifier and is positional only.

fetch_tracks async classmethod

fetch_tracks(
    query: str, /, *, node: Node | None = None
) -> list[Playable] | Playlist

Search for tracks through the Pool.

This method will use the provided node or find the best available node to perform the search. Results are automatically cached if the LFU cache is active.

Parameters:

Name	Type	Description	Default
query	str	The search query to perform.	required
node	Node | None	An optional node to use for the search. Defaults to None.	None

Returns:

Type	Description
list[:class:`~revvlink.Playable`] | :class:`~revvlink.Playlist`	The search results.

Raises:

Type	Description
LavalinkLoadException	Exception raised when Lavalink fails to load results based on your query.

cache classmethod

cache(capacity: int | None | bool = None) -> None

Configure or resize the LFU track cache.

Parameters:

Name	Type	Description	Default
capacity	int | None | bool	The new capacity for the cache. Passing None, False, or a value <= 0 will disable the cache.	None

Raises:

Type	Description
ValueError	The capacity provided was not an integer, None, or boolean.

has_cache classmethod

has_cache() -> bool

Whether the LFU track cache is currently active.

Returns:

Type	Description
bool	True if active, False otherwise.