Safe and sane multi-item storage removal (#11490)

* Fix overlay prefix removal result

* Second part of the overlay prefix removal fix.

* Report only items deleted from storage in clear_prefix

* Fix kill_prefix

* Formatting

* Remove unused code

* Fixes

* Fixes

* Introduce clear_prefix host function v3

* Formatting

* Use v2 for now

* Fixes

* Formatting

* Docs

* Child prefix removal should also hide v3 for now

* Fixes

* Fixes

* Formatting

* Fixes

* apply_to_keys_whle takes start_at

* apply_to_keys_whle takes start_at

* apply_to_keys_whle takes start_at

* Cursor API; force limits

* Use unsafe deprecated functions

* Formatting

* Fixes

* Grumbles

* Fixes

* Docs

* Some nitpicks 🙈

* Update primitives/externalities/src/lib.rs

Co-authored-by: Bastian Köcher <bkchr@users.noreply.github.com>

* Formatting

* Fixes

* cargo fmt

* Fixes

* Update primitives/io/src/lib.rs

Co-authored-by: Keith Yeung <kungfukeith11@gmail.com>

* Formatting

* Fixes

Co-authored-by: Bastian Köcher <info@kchr.de>
Co-authored-by: Bastian Köcher <bkchr@users.noreply.github.com>
Co-authored-by: Keith Yeung <kungfukeith11@gmail.com>

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

@@ -96,10 +96,63 @@ pub fn kill(key: &[u8]) {
 }
 
 /// Ensure keys with the given `prefix` have no entries in storage.
+#[deprecated = "Use `clear_prefix` instead"]
 pub fn kill_prefix(prefix: &[u8], limit: Option<u32>) -> sp_io::KillStorageResult {
+	// TODO: Once the network has upgraded to include the new host functions, this code can be
+	// enabled.
+	// clear_prefix(prefix, limit).into()
 	sp_io::storage::clear_prefix(prefix, limit)
 }
 
+/// Partially clear the storage of all keys under a common `prefix`.
+///
+/// # Limit
+///
+/// A *limit* should always be provided through `maybe_limit`. This is one fewer than the
+/// maximum number of backend iterations which may be done by this operation and as such
+/// represents the maximum number of backend deletions which may happen. A *limit* of zero
+/// implies that no keys will be deleted, though there may be a single iteration done.
+///
+/// The limit can be used to partially delete storage items in case it is too large or costly
+/// to delete all in a single operation.
+///
+/// # Cursor
+///
+/// A *cursor* may be passed in to this operation with `maybe_cursor`. `None` should only be
+/// passed once (in the initial call) for any attempt to clear storage. In general, subsequent calls
+/// operating on the same prefix should pass `Some` and this value should be equal to the
+/// previous call result's `maybe_cursor` field. The only exception to this is when you can
+/// guarantee that the subsequent call is in a new block; in this case the previous call's result
+/// cursor need not be passed in an a `None` may be passed instead. This exception may be useful
+/// then making this call solely from a block-hook such as `on_initialize`.
+///
+/// Returns [`MultiRemovalResults`](sp_io::MultiRemovalResults) to inform about the result. Once the
+/// resultant `maybe_cursor` field is `None`, then no further items remain to be deleted.
+///
+/// NOTE: After the initial call for any given child storage, it is important that no keys further
+/// keys are inserted. If so, then they may or may not be deleted by subsequent calls.
+///
+/// # Note
+///
+/// Please note that keys which are residing in the overlay for the child are deleted without
+/// counting towards the `limit`.
+pub fn clear_prefix(
+	prefix: &[u8],
+	maybe_limit: Option<u32>,
+	_maybe_cursor: Option<&[u8]>,
+) -> sp_io::MultiRemovalResults {
+	// TODO: Once the network has upgraded to include the new host functions, this code can be
+	// enabled.
+	// sp_io::storage::clear_prefix(prefix, maybe_limit, maybe_cursor)
+	use sp_io::{KillStorageResult::*, MultiRemovalResults};
+	#[allow(deprecated)]
+	let (maybe_cursor, i) = match kill_prefix(prefix, maybe_limit) {
+		AllRemoved(i) => (None, i),
+		SomeRemaining(i) => (Some(prefix.to_vec()), i),
+	};
+	MultiRemovalResults { maybe_cursor, backend: i, unique: i, loops: i }
+}
+
 /// Get a Vec of bytes from storage.
 pub fn get_raw(key: &[u8]) -> Option<Vec<u8>> {
 	sp_io::storage::get(key)