listengroup

ListenGroup is meant to collect a group of network listeners into a single entity, and help track connections made against those listeners.

lib.rs:

Abstraction over a group of listeners and connections generated by them.

A ListenerGroup is a set of network listeners that are bound to the same basic connection handler logic.

Usage overview

An application calls [ListenerGroup::new()] to create a new ListenerGroup object. To the new() function it must pass an object that implements the GroupHandler trait. The object that implements GroupHandler is responsible the shared data among all listeners while the implementation of the GroupHandler's trait methods are responsible for the shared logic. Of special note is the [GroupHandler::connected()] trait method, whose responsibility it is to return an object that implements the ConnHandler trait.

The ConnHandler implementation has two special trait methods of note. The [ConnHandler::run()] is called once a connection has been established. The application should implement the connection management logic in this method. When the [ConnHandler::kill()] is called, the application must perform some logic that will abort the connection and return from the ConnHandler::run() implementation.

Once a ListenerGroup object has been created, the application calls [ListenerGroup::add_listener()] to add a listener. A background task will begin listening for incoming connections immediately.

When an application is done with a ListenerGroup it can call [ListenerGroup::shutdown()] to shut down all listeners and connections in an orderly fashion (as long as the ConnHandler::kill() method has been correctly implemented by the application).

Per-listener context

The ListenerGroup uses a single GroupHandler object for all listeners. If the application needs per-listener-specific data, it can use an associative container (like a HashMap) in its GroupHandler object to map listeners' unique identifiers to listener-specific contexts in the container. See the per_listener_ctx example in lstngrp's repository for an example implementation of this.