#10576: generic utility to unsubscribe from broadcast upon drop of the rx-side. (#10708)

* #10576: refactor `sc-utils::notification` and `sc-client-api::notifications`, so that they use common subscribe/unsubscribe routines * Add some docs. Reorganise `sc-utils::notification` * `sc-clent-api::notifications` and `sc-utils::notification` — ensure the SubscriptionGuard is dropped before the Rx-channel * `sc-utils::pubsub::SubscriptionGuard` make it a bit more ergonomic. Let the `Rx` to be put inside of the `SubscriptionGuard`, so that the latter shall guarantee the order: - first unsubscribe; - then drop the `Rx`. * Being less zealous with splitting the modules into little pieces * rework pubsub: the concrete usage should only define a good registry type * sc-client-api::notifications: make it comply with the reworked pubsub * cargo fmt * make sc-client-api tests work * Address the review notes * cargo fmt * Describe the behaviour of pubsub registry * Doc-comments for module `sc-utils::pubsub` * Fix: it used to send notifications regardless of the filter setup during subscription * `sc-client-api::StorageNotifications` the API does not have to require mut-self-reference. As a result `sc-service::Client` does not have to wrap its `storage_notifications` into a Mutex. * cargo fmt * Several changes addressing the notes by @bckhr. - Remove the `impl Default for StorageNotifications<Block>`; - no need for groupping the `remove_from` and `listen_from` into a separate `helpers` module; - remove unnecessary import `use registry::SubscribeOp`. * Add a doc-comment to the `sc-client::notifications::SubscribeOp` * As per @bkchr note on the unproven assertion: behave gracefully upon receiving a duplicate subscription-ID. * sc-utils::pubsub: log when a registry yields an ID that does point to an existing sink * `sc-utils::notifications`: payload materialized lazily * Update Cargo.lock (after adding `log` as a dependency to the `sc-utils`) * `sc-client-api::notifications`: introduce a struct (instead of a type def) for the notification message * Get rid of `sc-utils::pubsub::Channel` trait (instead just use the `sc-utils::mpsc`) * The SubsID is no more generic: the fact it is a `Copy` is known — no need to pass it by ref * sc-utils::pubsub internals do not have to be generic over the channel type * Rename Hub::dispatch into Hub::send * That method was unnecessary (`SubscriberSink::render_notification`) * cargo fmt * No need for a separate UnsubscribeGuard type * Ditch the type-def of SubsID in the sc-utils::pubsub, instead — just use the crate::id_sequence::SeqID * Return the <Registry as Dispatch>::Ret when sending an item * Make the `Hub<M, R>::lock_registry(...)` method more ergonomic * cargo doc links * cargo doc links * Use a simpler name for the type * cargo doc links * Derive `Default` rather than implement it * Derive `Default` rather than implement it * Remove an unnecessary usage of type_name * Define a more cautious order between sinks.remove->registry.unsubscribe and registry.subscribe->sinks.insert * Hub: lock_registry_for_tests->map_registry_for_tests — a safer choice for a public API * Replace Mutex over the shared Registry with a ReentrableMutex+RefCell * sc-utils::pubsub: add tests for a panicking registry * Add the missing copyright headers * Arc<Vec<_>> -> Arc<[_]>
2026-04-26 05:17:58 +00:00 · 2022-02-28 23:51:35 +02:00
parent 89b5dafc29
commit 4009148889
19 changed files with 1609 additions and 677 deletions
@@ -0,0 +1,54 @@
+// This file is part of Substrate.
+
+// Copyright (C) 2020-2022 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
+
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+//! Produce opaque sequential IDs.
+
+/// A Sequence of IDs.
+#[derive(Debug, Default)]
+// The `Clone` trait is intentionally not defined on this type.
+pub struct IDSequence {
+	next_id: u64,
+}
+
+/// A Sequential ID.
+///
+/// Its integer value is intentionally not public: it is supposed to be instantiated from within
+/// this module only.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
+pub struct SeqID(u64);
+
+impl std::fmt::Display for SeqID {
+	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+		write!(f, "{}", self.0)
+	}
+}
+
+impl IDSequence {
+	/// Create a new ID-sequence.
+	pub fn new() -> Self {
+		Default::default()
+	}
+
+	/// Obtain another ID from this sequence.
+	pub fn next_id(&mut self) -> SeqID {
+		let id = SeqID(self.next_id);
+		self.next_id += 1;
+
+		id
+	}
+}
@@ -36,7 +36,9 @@
 //! | entity       | Name of channel passed to `tracing_unbounded` |
 //! | action       | One of `send`/`received`/`dropped`            |

+pub mod id_sequence;
 pub mod metrics;
 pub mod mpsc;
 pub mod notification;
+pub mod pubsub;
 pub mod status_sinks;
@@ -26,15 +26,19 @@
 //!
 //! See [`sc-service::builder::RpcExtensionBuilder`] for more details.

-use std::{marker::PhantomData, sync::Arc};
+use futures::stream::{FusedStream, Stream};
+use std::{
+	pin::Pin,
+	task::{Context, Poll},
+};

-use crate::mpsc::{tracing_unbounded, TracingUnboundedReceiver, TracingUnboundedSender};
+use crate::pubsub::{Hub, Receiver};

-use parking_lot::Mutex;
+mod registry;
+use registry::Registry;

-/// Collection of channel sending endpoints shared with the receiver side
-/// so they can register themselves.
-type SharedSenders<Payload> = Arc<Mutex<Vec<TracingUnboundedSender<Payload>>>>;
+#[cfg(test)]
+mod tests;

 /// Trait used to define the "tracing key" string used to tag
 /// and identify the mpsc channels.
@@ -44,108 +48,75 @@ pub trait TracingKeyStr {
 	const TRACING_KEY: &'static str;
 }

-/// The sending half of the notifications channel(s).
+/// The receiving half of the notifications channel.
 ///
-/// Used to send notifications from the BEEFY gadget side.
+/// The [`NotificationStream`] entity stores the [`Hub`] so it can be
+/// used to add more subscriptions.
 #[derive(Clone)]
-pub struct NotificationSender<Payload: Clone> {
-	subscribers: SharedSenders<Payload>,
+pub struct NotificationStream<Payload, TK: TracingKeyStr> {
+	hub: Hub<Payload, Registry>,
+	_pd: std::marker::PhantomData<TK>,
 }

-impl<Payload: Clone> NotificationSender<Payload> {
-	/// The `subscribers` should be shared with a corresponding `NotificationStream`.
-	fn new(subscribers: SharedSenders<Payload>) -> Self {
-		Self { subscribers }
+/// The receiving half of the notifications channel(s).
+#[derive(Debug)]
+pub struct NotificationReceiver<Payload> {
+	receiver: Receiver<Payload, Registry>,
+}
+
+/// The sending half of the notifications channel(s).
+pub struct NotificationSender<Payload> {
+	hub: Hub<Payload, Registry>,
+}
+
+impl<Payload, TK: TracingKeyStr> NotificationStream<Payload, TK> {
+	/// Creates a new pair of receiver and sender of `Payload` notifications.
+	pub fn channel() -> (NotificationSender<Payload>, Self) {
+		let hub = Hub::new(TK::TRACING_KEY);
+		let sender = NotificationSender { hub: hub.clone() };
+		let receiver = NotificationStream { hub, _pd: Default::default() };
+		(sender, receiver)
 	}

+	/// Subscribe to a channel through which the generic payload can be received.
+	pub fn subscribe(&self) -> NotificationReceiver<Payload> {
+		let receiver = self.hub.subscribe(());
+		NotificationReceiver { receiver }
+	}
+}
+
+impl<Payload> NotificationSender<Payload> {
 	/// Send out a notification to all subscribers that a new payload is available for a
 	/// block.
 	pub fn notify<Error>(
 		&self,
 		payload: impl FnOnce() -> Result<Payload, Error>,
-	) -> Result<(), Error> {
-		let mut subscribers = self.subscribers.lock();
-
-		// do an initial prune on closed subscriptions
-		subscribers.retain(|n| !n.is_closed());
-
-		if !subscribers.is_empty() {
-			let payload = payload()?;
-			subscribers.retain(|n| n.unbounded_send(payload.clone()).is_ok());
-		}
-
-		Ok(())
+	) -> Result<(), Error>
+	where
+		Payload: Clone,
+	{
+		self.hub.send(payload)
 	}
 }

-/// The receiving half of the notifications channel.
-///
-/// The `NotificationStream` entity stores the `SharedSenders` so it can be
-/// used to add more subscriptions.
-#[derive(Clone)]
-pub struct NotificationStream<Payload: Clone, TK: TracingKeyStr> {
-	subscribers: SharedSenders<Payload>,
-	_trace_key: PhantomData<TK>,
-}
-
-impl<Payload: Clone, TK: TracingKeyStr> NotificationStream<Payload, TK> {
-	/// Creates a new pair of receiver and sender of `Payload` notifications.
-	pub fn channel() -> (NotificationSender<Payload>, Self) {
-		let subscribers = Arc::new(Mutex::new(vec![]));
-		let receiver = NotificationStream::new(subscribers.clone());
-		let sender = NotificationSender::new(subscribers);
-		(sender, receiver)
-	}
-
-	/// Create a new receiver of `Payload` notifications.
-	///
-	/// The `subscribers` should be shared with a corresponding `NotificationSender`.
-	fn new(subscribers: SharedSenders<Payload>) -> Self {
-		Self { subscribers, _trace_key: PhantomData }
-	}
-
-	/// Subscribe to a channel through which the generic payload can be received.
-	pub fn subscribe(&self) -> TracingUnboundedReceiver<Payload> {
-		let (sender, receiver) = tracing_unbounded(TK::TRACING_KEY);
-		self.subscribers.lock().push(sender);
-		receiver
+impl<Payload> Clone for NotificationSender<Payload> {
+	fn clone(&self) -> Self {
+		Self { hub: self.hub.clone() }
 	}
 }

-#[cfg(test)]
-mod tests {
-	use super::*;
-	use futures::StreamExt;
+impl<Payload> Unpin for NotificationReceiver<Payload> {}

-	#[derive(Clone)]
-	pub struct DummyTracingKey;
-	impl TracingKeyStr for DummyTracingKey {
-		const TRACING_KEY: &'static str = "test_notification_stream";
-	}
+impl<Payload> Stream for NotificationReceiver<Payload> {
+	type Item = Payload;

-	type StringStream = NotificationStream<String, DummyTracingKey>;
-
-	#[test]
-	fn notification_channel_simple() {
-		let (sender, stream) = StringStream::channel();
-
-		let test_payload = String::from("test payload");
-		let closure_payload = test_payload.clone();
-
-		// Create a future to receive a single notification
-		// from the stream and verify its payload.
-		let future = stream.subscribe().take(1).for_each(move |payload| {
-			let test_payload = closure_payload.clone();
-			async move {
-				assert_eq!(payload, test_payload);
-			}
-		});
-
-		// Send notification.
-		let r: std::result::Result<(), ()> = sender.notify(|| Ok(test_payload));
-		r.unwrap();
-
-		// Run receiver future.
-		tokio_test::block_on(future);
+	fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Payload>> {
+		Pin::new(&mut self.get_mut().receiver).poll_next(cx)
+	}
+}
+
+impl<Payload> FusedStream for NotificationReceiver<Payload> {
+	fn is_terminated(&self) -> bool {
+		self.receiver.is_terminated()
 	}
 }
@@ -0,0 +1,63 @@
+// This file is part of Substrate.
+
+// Copyright (C) 2021-2022 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
+
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+use std::collections::HashSet;
+
+use crate::{
+	id_sequence::SeqID,
+	pubsub::{Dispatch, Subscribe, Unsubscribe},
+};
+
+/// The shared structure to keep track on subscribers.
+#[derive(Debug, Default)]
+pub(super) struct Registry {
+	pub(super) subscribers: HashSet<SeqID>,
+}
+
+impl Subscribe<()> for Registry {
+	fn subscribe(&mut self, _subs_key: (), subs_id: SeqID) {
+		self.subscribers.insert(subs_id);
+	}
+}
+impl Unsubscribe for Registry {
+	fn unsubscribe(&mut self, subs_id: SeqID) {
+		self.subscribers.remove(&subs_id);
+	}
+}
+
+impl<MakePayload, Payload, Error> Dispatch<MakePayload> for Registry
+where
+	MakePayload: FnOnce() -> Result<Payload, Error>,
+	Payload: Clone,
+{
+	type Item = Payload;
+	type Ret = Result<(), Error>;
+
+	fn dispatch<F>(&mut self, make_payload: MakePayload, mut dispatch: F) -> Self::Ret
+	where
+		F: FnMut(&SeqID, Self::Item),
+	{
+		if !self.subscribers.is_empty() {
+			let payload = make_payload()?;
+			for subs_id in &self.subscribers {
+				dispatch(subs_id, payload.clone());
+			}
+		}
+		Ok(())
+	}
+}
@@ -0,0 +1,52 @@
+// This file is part of Substrate.
+
+// Copyright (C) 2021-2022 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
+
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+use super::*;
+use futures::StreamExt;
+
+#[derive(Clone)]
+pub struct DummyTracingKey;
+impl TracingKeyStr for DummyTracingKey {
+	const TRACING_KEY: &'static str = "test_notification_stream";
+}
+
+type StringStream = NotificationStream<String, DummyTracingKey>;
+
+#[test]
+fn notification_channel_simple() {
+	let (sender, stream) = StringStream::channel();
+
+	let test_payload = String::from("test payload");
+	let closure_payload = test_payload.clone();
+
+	// Create a future to receive a single notification
+	// from the stream and verify its payload.
+	let future = stream.subscribe().take(1).for_each(move |payload| {
+		let test_payload = closure_payload.clone();
+		async move {
+			assert_eq!(payload, test_payload);
+		}
+	});
+
+	// Send notification.
+	let r: std::result::Result<(), ()> = sender.notify(|| Ok(test_payload));
+	r.unwrap();
+
+	// Run receiver future.
+	tokio_test::block_on(future);
+}
@@ -0,0 +1,263 @@
+// This file is part of Substrate.
+
+// Copyright (C) 2021-2022 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
+
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+//! Provides means to implement a typical Pub/Sub mechanism.
+//!
+//! This module provides a type [`Hub`] which can be used both to subscribe,
+//! and to send the broadcast messages.
+//!
+//! The [`Hub`] type is parametrized by two other types:
+//! - `Message` — the type of a message that shall be delivered to the subscribers;
+//! - `Registry` — implementation of the subscription/dispatch logic.
+//!
+//! A Registry is implemented by defining the following traits:
+//! - [`Subscribe<K>`];
+//! - [`Dispatch<M>`];
+//! - [`Unsubscribe`].
+//!
+//! As a result of subscription `Hub::subscribe` method returns an instance of
+//! [`Receiver<Message,Registry>`]. That can be used as a [`Stream`] to receive the messages.
+//! Upon drop the [`Receiver<Message, Registry>`] shall unregister itself from the `Hub`.
+
+use std::{
+	collections::HashMap,
+	pin::Pin,
+	sync::{Arc, Weak},
+	task::{Context, Poll},
+};
+
+use futures::stream::{FusedStream, Stream};
+// use parking_lot::Mutex;
+use parking_lot::ReentrantMutex;
+use std::cell::RefCell;
+
+use crate::{
+	id_sequence::SeqID,
+	mpsc::{TracingUnboundedReceiver, TracingUnboundedSender},
+};
+
+#[cfg(test)]
+mod tests;
+
+/// Unsubscribe: unregisters a previously created subscription.
+pub trait Unsubscribe {
+	/// Remove all registrations of the subscriber with ID `subs_id`.
+	fn unsubscribe(&mut self, subs_id: SeqID);
+}
+
+/// Subscribe using a key of type `K`
+pub trait Subscribe<K> {
+	/// Register subscriber with the ID `subs_id` as having interest to the key `K`.
+	fn subscribe(&mut self, subs_key: K, subs_id: SeqID);
+}
+
+/// Dispatch a message of type `M`.
+pub trait Dispatch<M> {
+	/// The type of the that shall be sent through the channel as a result of such dispatch.
+	type Item;
+	/// The type returned by the `dispatch`-method.
+	type Ret;
+
+	/// Dispatch the message of type `M`.
+	///
+	/// The implementation is given an instance of `M` and is supposed to invoke `dispatch` for
+	/// each matching subscriber, with an argument of type `Self::Item` matching that subscriber.
+	///
+	/// Note that this does not have to be of the same type with the item that will be sent through
+	/// to the subscribers. The subscribers will receive a message of type `Self::Item`.
+	fn dispatch<F>(&mut self, message: M, dispatch: F) -> Self::Ret
+	where
+		F: FnMut(&SeqID, Self::Item);
+}
+
+/// A subscription hub.
+///
+/// Does the subscription and dispatch.
+/// The exact subscription and routing behaviour is to be implemented by the Registry (of type `R`).
+/// The Hub under the hood uses the channel defined in `crate::mpsc` module.
+#[derive(Debug)]
+pub struct Hub<M, R> {
+	tracing_key: &'static str,
+	shared: Arc<ReentrantMutex<RefCell<Shared<M, R>>>>,
+}
+
+/// The receiving side of the subscription.
+///
+/// The messages are delivered as items of a [`Stream`].
+/// Upon drop this receiver unsubscribes itself from the [`Hub<M, R>`].
+#[derive(Debug)]
+pub struct Receiver<M, R>
+where
+	R: Unsubscribe,
+{
+	rx: TracingUnboundedReceiver<M>,
+
+	shared: Weak<ReentrantMutex<RefCell<Shared<M, R>>>>,
+	subs_id: SeqID,
+}
+
+#[derive(Debug)]
+struct Shared<M, R> {
+	id_sequence: crate::id_sequence::IDSequence,
+	registry: R,
+	sinks: HashMap<SeqID, TracingUnboundedSender<M>>,
+}
+
+impl<M, R> Hub<M, R>
+where
+	R: Unsubscribe,
+{
+	/// Provide access to the registry (for test purposes).
+	pub fn map_registry_for_tests<MapF, Ret>(&self, map: MapF) -> Ret
+	where
+		MapF: FnOnce(&R) -> Ret,
+	{
+		let shared_locked = self.shared.lock();
+		let shared_borrowed = shared_locked.borrow();
+		map(&shared_borrowed.registry)
+	}
+}
+
+impl<M, R> Drop for Receiver<M, R>
+where
+	R: Unsubscribe,
+{
+	fn drop(&mut self) {
+		if let Some(shared) = self.shared.upgrade() {
+			shared.lock().borrow_mut().unsubscribe(self.subs_id);
+		}
+	}
+}
+
+impl<M, R> Hub<M, R> {
+	/// Create a new instance of Hub (with default value for the Registry).
+	pub fn new(tracing_key: &'static str) -> Self
+	where
+		R: Default,
+	{
+		Self::new_with_registry(tracing_key, Default::default())
+	}
+
+	/// Create a new instance of Hub over the initialized Registry.
+	pub fn new_with_registry(tracing_key: &'static str, registry: R) -> Self {
+		let shared =
+			Shared { registry, sinks: Default::default(), id_sequence: Default::default() };
+		let shared = Arc::new(ReentrantMutex::new(RefCell::new(shared)));
+		Self { tracing_key, shared }
+	}
+
+	/// Subscribe to this Hub using the `subs_key: K`.
+	///
+	/// A subscription with a key `K` is possible if the Registry implements `Subscribe<K>`.
+	pub fn subscribe<K>(&self, subs_key: K) -> Receiver<M, R>
+	where
+		R: Subscribe<K> + Unsubscribe,
+	{
+		let shared_locked = self.shared.lock();
+		let mut shared_borrowed = shared_locked.borrow_mut();
+
+		let subs_id = shared_borrowed.id_sequence.next_id();
+
+		// The order (registry.subscribe then sinks.insert) is important here:
+		// assuming that `Subscribe<K>::subscribe` can panic, it is better to at least
+		// have the sink disposed.
+		shared_borrowed.registry.subscribe(subs_key, subs_id);
+
+		let (tx, rx) = crate::mpsc::tracing_unbounded(self.tracing_key);
+		assert!(shared_borrowed.sinks.insert(subs_id, tx).is_none(), "Used IDSequence to create another ID. Should be unique until u64 is overflowed. Should be unique.");
+
+		Receiver { shared: Arc::downgrade(&self.shared), subs_id, rx }
+	}
+
+	/// Send the message produced with `Trigger`.
+	///
+	/// This is possible if the registry implements `Dispatch<Trigger, Item = M>`.
+	pub fn send<Trigger>(&self, trigger: Trigger) -> <R as Dispatch<Trigger>>::Ret
+	where
+		R: Dispatch<Trigger, Item = M>,
+	{
+		let shared_locked = self.shared.lock();
+		let mut shared_borrowed = shared_locked.borrow_mut();
+		let (registry, sinks) = shared_borrowed.get_mut();
+
+		let dispatch_result = registry.dispatch(trigger, |subs_id, item| {
+			if let Some(tx) = sinks.get_mut(&subs_id) {
+				if let Err(send_err) = tx.unbounded_send(item) {
+					log::warn!("Sink with SubsID = {} failed to perform unbounded_send: {} ({} as Dispatch<{}, Item = {}>::dispatch(...))", subs_id, send_err, std::any::type_name::<R>(),
+					std::any::type_name::<Trigger>(),
+					std::any::type_name::<M>());
+				}
+			} else {
+				log::warn!(
+					"No Sink for SubsID = {} ({} as Dispatch<{}, Item = {}>::dispatch(...))",
+					subs_id,
+					std::any::type_name::<R>(),
+					std::any::type_name::<Trigger>(),
+					std::any::type_name::<M>(),
+				);
+			}
+		});
+
+		dispatch_result
+	}
+}
+
+impl<M, R> Shared<M, R> {
+	fn get_mut(&mut self) -> (&mut R, &mut HashMap<SeqID, TracingUnboundedSender<M>>) {
+		(&mut self.registry, &mut self.sinks)
+	}
+
+	fn unsubscribe(&mut self, subs_id: SeqID)
+	where
+		R: Unsubscribe,
+	{
+		// The order (sinks.remove then registry.unsubscribe) is important here:
+		// assuming that `Unsubscribe::unsubscribe` can panic, it is better to at least
+		// have the sink disposed.
+		self.sinks.remove(&subs_id);
+		self.registry.unsubscribe(subs_id);
+	}
+}
+
+impl<M, R> Clone for Hub<M, R> {
+	fn clone(&self) -> Self {
+		Self { tracing_key: self.tracing_key, shared: self.shared.clone() }
+	}
+}
+
+impl<M, R> Unpin for Receiver<M, R> where R: Unsubscribe {}
+
+impl<M, R> Stream for Receiver<M, R>
+where
+	R: Unsubscribe,
+{
+	type Item = M;
+
+	fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
+		Pin::new(&mut self.get_mut().rx).poll_next(cx)
+	}
+}
+
+impl<Ch, R> FusedStream for Receiver<Ch, R>
+where
+	R: Unsubscribe,
+{
+	fn is_terminated(&self) -> bool {
+		self.rx.is_terminated()
+	}
+}
@@ -0,0 +1,123 @@
+// This file is part of Substrate.
+
+// Copyright (C) 2020-2022 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
+
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+use futures::StreamExt;
+use tokio_test::block_on;
+
+use super::*;
+
+mod normal_operation;
+mod panicking_registry;
+
+const TK: &str = "a_tracing_key";
+
+type Message = u64;
+type TestHub = Hub<Message, Registry>;
+type TestReceiver = Receiver<Message, Registry>;
+
+#[derive(Default)]
+struct Registry {
+	subscribers: HashMap<SeqID, SubsKey>,
+}
+
+struct SubsKey {
+	_receiver: Option<TestReceiver>,
+	panic: SubsKeyPanic,
+}
+
+impl SubsKey {
+	fn new() -> Self {
+		Self { _receiver: None, panic: SubsKeyPanic::None }
+	}
+	fn with_receiver(self, receiver: TestReceiver) -> Self {
+		Self { _receiver: Some(receiver), ..self }
+	}
+	fn with_panic(self, panic: SubsKeyPanic) -> Self {
+		Self { panic, ..self }
+	}
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum SubsKeyPanic {
+	None,
+
+	OnSubscribePanicBefore,
+	OnSubscribePanicAfter,
+
+	OnUnsubscribePanicBefore,
+	OnUnsubscribePanicAfter,
+
+	OnDispatchPanicBefore,
+	OnDispatchPanicAfter,
+}
+
+impl<M> Hub<M, Registry> {
+	fn subs_count(&self) -> usize {
+		self.map_registry_for_tests(|r| r.subscribers.len())
+	}
+	fn sink_count(&self) -> usize {
+		self.shared.lock().borrow().sinks.len()
+	}
+}
+
+impl Subscribe<SubsKey> for Registry {
+	fn subscribe(&mut self, subs_key: SubsKey, subs_id: SeqID) {
+		let sk_panic = subs_key.panic;
+
+		if sk_panic == SubsKeyPanic::OnSubscribePanicBefore {
+			panic!("on-subscribe-panic-before")
+		}
+		self.subscribers.insert(subs_id, subs_key);
+		if sk_panic == SubsKeyPanic::OnSubscribePanicAfter {
+			panic!("on-subscribe-panic-after")
+		}
+	}
+}
+impl Unsubscribe for Registry {
+	fn unsubscribe(&mut self, subs_id: SeqID) {
+		let sk_panic =
+			self.subscribers.get(&subs_id).map(|sk| sk.panic).unwrap_or(SubsKeyPanic::None);
+
+		if sk_panic == SubsKeyPanic::OnUnsubscribePanicBefore {
+			panic!("on-unsubscribe-panic-before")
+		}
+		self.subscribers.remove(&subs_id);
+		if sk_panic == SubsKeyPanic::OnUnsubscribePanicAfter {
+			panic!("on-unsubscribe-panic-after")
+		}
+	}
+}
+impl Dispatch<Message> for Registry {
+	type Item = Message;
+	type Ret = ();
+
+	fn dispatch<F>(&mut self, message: Message, mut dispatch: F) -> Self::Ret
+	where
+		F: FnMut(&SeqID, Self::Item),
+	{
+		self.subscribers.iter().for_each(|(id, subs_key)| {
+			if subs_key.panic == SubsKeyPanic::OnDispatchPanicBefore {
+				panic!("on-dispatch-panic-before")
+			}
+			dispatch(id, message);
+			if subs_key.panic == SubsKeyPanic::OnDispatchPanicAfter {
+				panic!("on-dispatch-panic-after")
+			}
+		});
+	}
+}
@@ -0,0 +1,88 @@
+// This file is part of Substrate.
+
+// Copyright (C) 2020-2022 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
+
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+use super::*;
+
+#[test]
+fn positive_rx_receives_relevant_messages_and_terminates_upon_hub_drop() {
+	block_on(async {
+		let hub = TestHub::new(TK);
+		assert_eq!(hub.subs_count(), 0);
+
+		// No subscribers yet. That message is not supposed to get to anyone.
+		hub.send(0);
+
+		let mut rx_01 = hub.subscribe(SubsKey::new());
+		assert_eq!(hub.subs_count(), 1);
+
+		// That message is sent after subscription. Should be delivered into rx_01.
+		hub.send(1);
+		assert_eq!(Some(1), rx_01.next().await);
+
+		// Hub is disposed. The rx_01 should be over after that.
+		std::mem::drop(hub);
+
+		assert!(!rx_01.is_terminated());
+		assert_eq!(None, rx_01.next().await);
+		assert!(rx_01.is_terminated());
+	});
+}
+
+#[test]
+fn positive_subs_count_is_correct_upon_drop_of_rxs() {
+	block_on(async {
+		let hub = TestHub::new(TK);
+		assert_eq!(hub.subs_count(), 0);
+
+		let rx_01 = hub.subscribe(SubsKey::new());
+		assert_eq!(hub.subs_count(), 1);
+		let rx_02 = hub.subscribe(SubsKey::new());
+		assert_eq!(hub.subs_count(), 2);
+
+		std::mem::drop(rx_01);
+		assert_eq!(hub.subs_count(), 1);
+		std::mem::drop(rx_02);
+		assert_eq!(hub.subs_count(), 0);
+	});
+}
+
+#[test]
+fn positive_subs_count_is_correct_upon_drop_of_rxs_on_cloned_hubs() {
+	block_on(async {
+		let hub_01 = TestHub::new(TK);
+		let hub_02 = hub_01.clone();
+		assert_eq!(hub_01.subs_count(), 0);
+		assert_eq!(hub_02.subs_count(), 0);
+
+		let rx_01 = hub_02.subscribe(SubsKey::new());
+		assert_eq!(hub_01.subs_count(), 1);
+		assert_eq!(hub_02.subs_count(), 1);
+
+		let rx_02 = hub_02.subscribe(SubsKey::new());
+		assert_eq!(hub_01.subs_count(), 2);
+		assert_eq!(hub_02.subs_count(), 2);
+
+		std::mem::drop(rx_01);
+		assert_eq!(hub_01.subs_count(), 1);
+		assert_eq!(hub_02.subs_count(), 1);
+
+		std::mem::drop(rx_02);
+		assert_eq!(hub_01.subs_count(), 0);
+		assert_eq!(hub_02.subs_count(), 0);
+	});
+}
@@ -0,0 +1,248 @@
+// This file is part of Substrate.
+
+// Copyright (C) 2020-2022 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
+
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+use super::*;
+
+use std::panic::{catch_unwind, AssertUnwindSafe};
+
+fn assert_hub_props(hub: &TestHub, sinks_count: usize, subs_count: usize) {
+	assert_eq!(hub.sink_count(), sinks_count);
+	assert_eq!(hub.subs_count(), subs_count);
+}
+
+#[test]
+fn t01() {
+	let hub = TestHub::new(TK);
+	assert_hub_props(&hub, 0, 0);
+
+	let rx_01 = hub.subscribe(SubsKey::new());
+	assert_hub_props(&hub, 1, 1);
+
+	std::mem::drop(rx_01);
+	assert_hub_props(&hub, 0, 0);
+}
+
+#[test]
+fn t02() {
+	block_on(async {
+		// Create a Hub
+		let hub = TestHub::new(TK);
+		assert_hub_props(&hub, 0, 0);
+
+		// Subscribe rx-01
+		let rx_01 = hub.subscribe(SubsKey::new());
+		assert_hub_props(&hub, 1, 1);
+
+		// Subscribe rx-02 so that its unsubscription will lead to an attempt to drop rx-01 in the
+		// middle of unsubscription of rx-02
+		let rx_02 = hub.subscribe(SubsKey::new().with_receiver(rx_01));
+		assert_hub_props(&hub, 2, 2);
+
+		// Subscribe rx-03 in order to see that it will receive messages after the unclean
+		// unsubscription
+		let mut rx_03 = hub.subscribe(SubsKey::new());
+		assert_hub_props(&hub, 3, 3);
+
+		// drop rx-02 leads to an attempt to unsubscribe rx-01
+		assert!(catch_unwind(AssertUnwindSafe(move || {
+			std::mem::drop(rx_02);
+		}))
+		.is_err());
+
+		// One of the rxes could not unsubscribe
+		assert_hub_props(&hub, 2, 2);
+
+		// Subscribe rx-04 in order to see that it will receive messages after the unclean
+		// unsubscription
+		let mut rx_04 = hub.subscribe(SubsKey::new());
+		assert_hub_props(&hub, 3, 3);
+
+		hub.send(2);
+
+		// The messages are still received
+		assert_eq!(rx_03.next().await, Some(2));
+		assert_eq!(rx_04.next().await, Some(2));
+
+		// Perform a clean unsubscription
+		std::mem::drop(rx_04);
+
+		hub.send(3);
+
+		// The messages are still received
+		assert_eq!(rx_03.next().await, Some(3));
+
+		std::mem::drop(rx_03);
+
+		hub.send(4);
+
+		// The stuck subscription is still there
+		assert_hub_props(&hub, 1, 1);
+	});
+}
+
+async fn add_some_subscribers_see_that_messages_are_delivered_and_unsubscribe(hub: &TestHub) {
+	let rx_01 = hub.subscribe(SubsKey::new());
+	let rx_02 = hub.subscribe(SubsKey::new());
+
+	hub.send(1);
+	hub.send(2);
+	hub.send(3);
+
+	assert_eq!(rx_01.take(3).collect::<Vec<_>>().await, vec![1, 2, 3]);
+
+	hub.send(4);
+	hub.send(5);
+	hub.send(6);
+
+	assert_eq!(rx_02.take(6).collect::<Vec<_>>().await, vec![1, 2, 3, 4, 5, 6]);
+}
+
+#[test]
+fn t03() {
+	block_on(async {
+		// Create a Hub
+		let hub = TestHub::new(TK);
+		assert_hub_props(&hub, 0, 0);
+		add_some_subscribers_see_that_messages_are_delivered_and_unsubscribe(&hub).await;
+		assert_hub_props(&hub, 0, 0);
+
+		assert!(catch_unwind(AssertUnwindSafe(
+			|| hub.subscribe(SubsKey::new().with_panic(SubsKeyPanic::OnSubscribePanicBefore))
+		))
+		.is_err());
+
+		assert_hub_props(&hub, 0, 0);
+		add_some_subscribers_see_that_messages_are_delivered_and_unsubscribe(&hub).await;
+		assert_hub_props(&hub, 0, 0);
+	});
+}
+
+#[test]
+fn t04() {
+	block_on(async {
+		let hub = TestHub::new(TK);
+
+		assert_hub_props(&hub, 0, 0);
+		add_some_subscribers_see_that_messages_are_delivered_and_unsubscribe(&hub).await;
+		assert_hub_props(&hub, 0, 0);
+
+		assert!(catch_unwind(AssertUnwindSafe(
+			|| hub.subscribe(SubsKey::new().with_panic(SubsKeyPanic::OnSubscribePanicAfter))
+		))
+		.is_err());
+
+		// the registry has panicked after it has added a subs-id into its internal storage — the
+		// sinks do not leak, although the subscriptions storage contains some garbage
+		assert_hub_props(&hub, 0, 1);
+		add_some_subscribers_see_that_messages_are_delivered_and_unsubscribe(&hub).await;
+		assert_hub_props(&hub, 0, 1);
+	})
+}
+
+#[test]
+fn t05() {
+	block_on(async {
+		let hub = TestHub::new(TK);
+
+		assert_hub_props(&hub, 0, 0);
+		add_some_subscribers_see_that_messages_are_delivered_and_unsubscribe(&hub).await;
+		assert_hub_props(&hub, 0, 0);
+
+		let rx_01 =
+			hub.subscribe(SubsKey::new().with_panic(SubsKeyPanic::OnUnsubscribePanicBefore));
+
+		assert_hub_props(&hub, 1, 1);
+		add_some_subscribers_see_that_messages_are_delivered_and_unsubscribe(&hub).await;
+		assert_hub_props(&hub, 1, 1);
+
+		assert!(catch_unwind(AssertUnwindSafe(move || std::mem::drop(rx_01))).is_err());
+
+		// the registry has panicked on-unsubscribe before it removed the subs-id from its internal
+		// storage — the sinks do not leak, although the subscriptions storage contains some garbage
+		assert_hub_props(&hub, 0, 1);
+		add_some_subscribers_see_that_messages_are_delivered_and_unsubscribe(&hub).await;
+		assert_hub_props(&hub, 0, 1);
+	})
+}
+
+#[test]
+fn t06() {
+	block_on(async {
+		let hub = TestHub::new(TK);
+
+		assert_hub_props(&hub, 0, 0);
+		add_some_subscribers_see_that_messages_are_delivered_and_unsubscribe(&hub).await;
+		assert_hub_props(&hub, 0, 0);
+
+		let rx_01 = hub.subscribe(SubsKey::new().with_panic(SubsKeyPanic::OnUnsubscribePanicAfter));
+
+		assert_hub_props(&hub, 1, 1);
+		add_some_subscribers_see_that_messages_are_delivered_and_unsubscribe(&hub).await;
+		assert_hub_props(&hub, 1, 1);
+
+		assert!(catch_unwind(AssertUnwindSafe(move || std::mem::drop(rx_01))).is_err());
+
+		// the registry has panicked on-unsubscribe after it removed the subs-id from its internal
+		// storage — the sinks do not leak, the subscriptions storage does not contain any garbage
+		assert_hub_props(&hub, 0, 0);
+		add_some_subscribers_see_that_messages_are_delivered_and_unsubscribe(&hub).await;
+		assert_hub_props(&hub, 0, 0);
+	})
+}
+
+#[test]
+fn t07() {
+	block_on(async {
+		let hub = TestHub::new(TK);
+
+		assert_hub_props(&hub, 0, 0);
+		add_some_subscribers_see_that_messages_are_delivered_and_unsubscribe(&hub).await;
+		assert_hub_props(&hub, 0, 0);
+
+		let rx_01 = hub.subscribe(SubsKey::new().with_panic(SubsKeyPanic::OnDispatchPanicBefore));
+		assert_hub_props(&hub, 1, 1);
+		assert!(catch_unwind(AssertUnwindSafe(|| hub.send(1))).is_err());
+		assert_hub_props(&hub, 1, 1);
+
+		std::mem::drop(rx_01);
+		assert_hub_props(&hub, 0, 0);
+		add_some_subscribers_see_that_messages_are_delivered_and_unsubscribe(&hub).await;
+		assert_hub_props(&hub, 0, 0);
+	})
+}
+
+#[test]
+fn t08() {
+	block_on(async {
+		let hub = TestHub::new(TK);
+
+		assert_hub_props(&hub, 0, 0);
+		add_some_subscribers_see_that_messages_are_delivered_and_unsubscribe(&hub).await;
+		assert_hub_props(&hub, 0, 0);
+
+		let rx_01 = hub.subscribe(SubsKey::new().with_panic(SubsKeyPanic::OnDispatchPanicAfter));
+		assert_hub_props(&hub, 1, 1);
+		assert!(catch_unwind(AssertUnwindSafe(|| hub.send(1))).is_err());
+		assert_hub_props(&hub, 1, 1);
+
+		std::mem::drop(rx_01);
+		assert_hub_props(&hub, 0, 0);
+		add_some_subscribers_see_that_messages_are_delivered_and_unsubscribe(&hub).await;
+		assert_hub_props(&hub, 0, 0);
+	})
+}