#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<[_]>

substrate/client/utils/src/notification/registry.rs

@@ -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(())
+	}
+}

substrate/client/utils/src/notification/tests.rs

@@ -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);
+}