Allow capping the amount of work performed when deleting a child trie (#7671)

* Allow Backend::for_keys_in_child_storage to be aborted by the closure

* Ext::kill_child_storage now takes an upper limit for backend deletion

* Add Storage::storage_kill_limited() runtime interface

* review: Use a new version of kill_storage instead of a new interface

* review: Simplify boolean expression

Co-authored-by: cheme <emericchevalier.pro@gmail.com>

* review: Rename for_keys_in_child_storage

Co-authored-by: cheme <emericchevalier.pro@gmail.com>

substrate/frame/support/src/storage/child.rs

@@ -25,6 +25,14 @@ use crate::sp_std::prelude::*;
 use codec::{Codec, Encode, Decode};
 pub use sp_core::storage::{ChildInfo, ChildType};
 
+/// The outcome of calling [`kill_storage`].
+pub enum KillOutcome {
+	/// No key remains in the child trie.
+	AllRemoved,
+	/// At least one key still resides in the child trie due to the supplied limit.
+	SomeRemaining,
+}
+
 /// Return the value of the item in storage under `key`, or `None` if there is no explicit entry.
 pub fn get<T: Decode + Sized>(
 	child_info: &ChildInfo,
@@ -148,13 +156,37 @@ pub fn exists(
 }
 
 /// Remove all `storage_key` key/values
+///
+/// Deletes all keys from the overlay and up to `limit` keys from the backend if
+/// it is set to `Some`. No limit is applied when `limit` is set to `None`.
+///
+/// The limit can be used to partially delete a child trie in case it is too large
+/// to delete in one go (block).
+///
+/// # Note
+///
+/// Please note that keys that are residing in the overlay for that child trie when
+/// issuing this call are all deleted without counting towards the `limit`. Only keys
+/// written during the current block are part of the overlay. Deleting with a `limit`
+/// mostly makes sense with an empty overlay for that child trie.
+///
+/// Calling this function multiple times per block for the same `storage_key` does
+/// not make much sense because it is not cumulative when called inside the same block.
+/// Use this function to distribute the deletion of a single child trie across multiple
+/// blocks.
 pub fn kill_storage(
 	child_info: &ChildInfo,
-) {
-	match child_info.child_type() {
+	limit: Option<u32>,
+) -> KillOutcome {
+	let all_removed = match child_info.child_type() {
 		ChildType::ParentKeyId => sp_io::default_child_storage::storage_kill(
 			child_info.storage_key(),
+			limit
 		),
+	};
+	match all_removed {
+		true => KillOutcome::AllRemoved,
+		false => KillOutcome::SomeRemaining,
 	}
 }