#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/transaction-pool/tests/pool.rs

@@ -387,7 +387,7 @@ fn should_push_watchers_during_maintenance() {
 	let header_hash = header.hash();
 	block_on(pool.maintain(block_event(header)));
 
-	let event = ChainEvent::Finalized { hash: header_hash.clone(), tree_route: Arc::new(vec![]) };
+	let event = ChainEvent::Finalized { hash: header_hash.clone(), tree_route: Arc::from(vec![]) };
 	block_on(pool.maintain(event));
 
 	// then
@@ -445,7 +445,7 @@ fn finalization() {
 	let event = ChainEvent::NewBestBlock { hash: header.hash(), tree_route: None };
 	block_on(pool.maintain(event));
 
-	let event = ChainEvent::Finalized { hash: header.hash(), tree_route: Arc::new(vec![]) };
+	let event = ChainEvent::Finalized { hash: header.hash(), tree_route: Arc::from(vec![]) };
 	block_on(pool.maintain(event));
 
 	let mut stream = futures::executor::block_on_stream(watcher);
@@ -493,7 +493,7 @@ fn fork_aware_finalization() {
 		b1 = header.hash();
 		block_on(pool.maintain(event));
 		assert_eq!(pool.status().ready, 0);
-		let event = ChainEvent::Finalized { hash: b1, tree_route: Arc::new(vec![]) };
+		let event = ChainEvent::Finalized { hash: b1, tree_route: Arc::from(vec![]) };
 		block_on(pool.maintain(event));
 	}
 
@@ -537,7 +537,7 @@ fn fork_aware_finalization() {
 		block_on(pool.maintain(event));
 		assert_eq!(pool.status().ready, 2);
 
-		let event = ChainEvent::Finalized { hash: header.hash(), tree_route: Arc::new(vec![]) };
+		let event = ChainEvent::Finalized { hash: header.hash(), tree_route: Arc::from(vec![]) };
 		block_on(pool.maintain(event));
 	}
 
@@ -554,7 +554,7 @@ fn fork_aware_finalization() {
 		d1 = header.hash();
 		block_on(pool.maintain(event));
 		assert_eq!(pool.status().ready, 2);
-		let event = ChainEvent::Finalized { hash: d1, tree_route: Arc::new(vec![]) };
+		let event = ChainEvent::Finalized { hash: d1, tree_route: Arc::from(vec![]) };
 		block_on(pool.maintain(event));
 	}
 
@@ -567,7 +567,7 @@ fn fork_aware_finalization() {
 		let event = ChainEvent::NewBestBlock { hash: header.hash(), tree_route: None };
 		block_on(pool.maintain(event));
 		assert_eq!(pool.status().ready, 0);
-		block_on(pool.maintain(ChainEvent::Finalized { hash: e1, tree_route: Arc::new(vec![]) }));
+		block_on(pool.maintain(ChainEvent::Finalized { hash: e1, tree_route: Arc::from(vec![]) }));
 	}
 
 	for (canon_watcher, h) in canon_watchers {
@@ -637,7 +637,7 @@ fn prune_and_retract_tx_at_same_time() {
 		block_on(pool.maintain(event));
 		assert_eq!(pool.status().ready, 0);
 
-		let event = ChainEvent::Finalized { hash: header.hash(), tree_route: Arc::new(vec![]) };
+		let event = ChainEvent::Finalized { hash: header.hash(), tree_route: Arc::from(vec![]) };
 		block_on(pool.maintain(event));
 
 		header.hash()