Tasks: general system for recognizing and executing service work (#1343)

`polkadot-sdk` version of original tasks PR located here: https://github.com/paritytech/substrate/pull/14329 Fixes #206 ## Status - [x] Generic `Task` trait - [x] `RuntimeTask` aggregated enum, compatible with `construct_runtime!` - [x] Casting between `Task` and `RuntimeTask` without needing `dyn` or `Box` - [x] Tasks Example pallet - [x] Runtime tests for Tasks example pallet - [x] Parsing for task-related macros - [x] Retrofit parsing to make macros optional - [x] Expansion for task-related macros - [x] Adds support for args in tasks - [x] Retrofit tasks example pallet to use macros instead of manual syntax - [x] Weights - [x] Cleanup - [x] UI tests - [x] Docs ## Target Syntax Adapted from https://github.com/paritytech/polkadot-sdk/issues/206#issue-1865172283 ```rust // NOTE: this enum is optional and is auto-generated by the other macros if not present #[pallet::task] pub enum Task<T: Config> { AddNumberIntoTotal { i: u32, } } /// Some running total. #[pallet::storage] pub(super) type Total<T: Config<I>, I: 'static = ()> = StorageValue<_, (u32, u32), ValueQuery>; /// Numbers to be added into the total. #[pallet::storage] pub(super) type Numbers<T: Config<I>, I: 'static = ()> = StorageMap<_, Twox64Concat, u32, u32, OptionQuery>; #[pallet::tasks_experimental] impl<T: Config<I>, I: 'static> Pallet<T, I> { /// Add a pair of numbers into the totals and remove them. #[pallet::task_list(Numbers::<T, I>::iter_keys())] #[pallet::task_condition(|i| Numbers::<T, I>::contains_key(i))] #[pallet::task_index(0)] pub fn add_number_into_total(i: u32) -> DispatchResult { let v = Numbers::<T, I>::take(i).ok_or(Error::<T, I>::NotFound)?; Total::<T, I>::mutate(|(total_keys, total_values)| { *total_keys += i; *total_values += v; }); Ok(()) } } ``` --------- Co-authored-by: Nikhil Gupta <17176722+gupnik@users.noreply.github.com> Co-authored-by: kianenigma <kian@parity.io> Co-authored-by: Nikhil Gupta <> Co-authored-by: Gavin Wood <gavin@parity.io> Co-authored-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io> Co-authored-by: gupnik <nikhilgupta.iitk@gmail.com>
2026-04-26 07:37:57 +00:00 · 2023-12-08 00:40:26 -05:00
parent 34c991e2cf
commit ac3f14d23b
75 changed files with 3516 additions and 24 deletions
@@ -695,6 +695,7 @@ mod weight_tests {
 			type BaseCallFilter: crate::traits::Contains<Self::RuntimeCall>;
 			type RuntimeOrigin;
 			type RuntimeCall;
+			type RuntimeTask;
 			type PalletInfo: crate::traits::PalletInfo;
 			type DbWeight: Get<crate::weights::RuntimeDbWeight>;
 		}
@@ -791,6 +792,7 @@ mod weight_tests {
 		type BaseCallFilter = crate::traits::Everything;
 		type RuntimeOrigin = RuntimeOrigin;
 		type RuntimeCall = RuntimeCall;
+		type RuntimeTask = RuntimeTask;
 		type DbWeight = DbWeight;
 		type PalletInfo = PalletInfo;
 	}
@@ -849,7 +849,7 @@ pub mod pallet_prelude {
 		},
 		traits::{
 			BuildGenesisConfig, ConstU32, EnsureOrigin, Get, GetDefault, GetStorageVersion, Hooks,
-			IsType, PalletInfoAccess, StorageInfoTrait, StorageVersion, TypedGet,
+			IsType, PalletInfoAccess, StorageInfoTrait, StorageVersion, Task, TypedGet,
 		},
 		Blake2_128, Blake2_128Concat, Blake2_256, CloneNoBound, DebugNoBound, EqNoBound, Identity,
 		PartialEqNoBound, RuntimeDebugNoBound, Twox128, Twox256, Twox64Concat,
@@ -2674,6 +2674,61 @@ pub mod pallet_macros {
 	/// }
 	/// ```
 	pub use frame_support_procedural::storage;
+	/// This attribute is attached to a function inside an `impl` block annoated with
+	/// [`pallet::tasks_experimental`](`tasks_experimental`) to define the conditions for a
+	/// given work item to be valid.
+	///
+	/// It takes a closure as input, which is then used to define the condition. The closure
+	/// should have the same signature as the function it is attached to, except that it should
+	/// return a `bool` instead.
+	pub use frame_support_procedural::task_condition;
+	/// This attribute is attached to a function inside an `impl` block annoated with
+	/// [`pallet::tasks_experimental`](`tasks_experimental`) to define the index of a given
+	/// work item.
+	///
+	/// It takes an integer literal as input, which is then used to define the index. This
+	/// index should be unique for each function in the `impl` block.
+	pub use frame_support_procedural::task_index;
+	/// This attribute is attached to a function inside an `impl` block annoated with
+	/// [`pallet::tasks_experimental`](`tasks_experimental`) to define an iterator over the
+	/// available work items for a task.
+	///
+	/// It takes an iterator as input that yields a tuple with same types as the function
+	/// arguments.
+	pub use frame_support_procedural::task_list;
+	/// This attribute is attached to a function inside an `impl` block annoated with
+	/// [`pallet::tasks_experimental`](`tasks_experimental`) define the weight of a given work
+	/// item.
+	///
+	/// It takes a closure as input, which should return a `Weight` value.
+	pub use frame_support_procedural::task_weight;
+	/// Allows you to define some service work that can be recognized by a script or an
+	/// off-chain worker. Such a script can then create and submit all such work items at any
+	/// given time.
+	///
+	/// These work items are defined as instances of the [`Task`](frame_support::traits::Task)
+	/// trait. [`pallet:tasks_experimental`](`tasks_experimental`) when attached to an `impl`
+	/// block inside a pallet, will generate an enum `Task<T>` whose variants are mapped to
+	/// functions inside this `impl` block.
+	///
+	/// Each such function must have the following set of attributes:
+	///
+	/// * [`pallet::task_list`](`task_list`)
+	/// * [`pallet::task_condition`](`task_condition`)
+	/// * [`pallet::task_weight`](`task_weight`)
+	/// * [`pallet::task_index`](`task_index`)
+	///
+	/// All of such Tasks are then aggregated into a `RuntimeTask` by
+	/// [`construct_runtime`](frame_support::construct_runtime).
+	///
+	/// Finally, the `RuntimeTask` can then used by a script or off-chain worker to create and
+	/// submit such tasks via an extrinsic defined in `frame_system` called `do_task`.
+	///
+	/// ## Example
+	#[doc = docify::embed!("src/tests/tasks.rs", tasks_example)]
+	/// Now, this can be executed as follows:
+	#[doc = docify::embed!("src/tests/tasks.rs", tasks_work)]
+	pub use frame_support_procedural::tasks_experimental;
 }

 #[deprecated(note = "Will be removed after July 2023; Use `sp_runtime::traits` directly instead.")]
@@ -63,6 +63,7 @@ mod tests {
 			type BaseCallFilter: crate::traits::Contains<Self::RuntimeCall>;
 			type RuntimeOrigin;
 			type RuntimeCall;
+			type RuntimeTask;
 			type PalletInfo: crate::traits::PalletInfo;
 			type DbWeight: Get<crate::weights::RuntimeDbWeight>;
 		}
@@ -129,6 +130,7 @@ mod tests {
 		type BaseCallFilter = crate::traits::Everything;
 		type RuntimeOrigin = RuntimeOrigin;
 		type RuntimeCall = RuntimeCall;
+		type RuntimeTask = RuntimeTask;
 		type PalletInfo = PalletInfo;
 		type DbWeight = ();
 	}
@@ -16,6 +16,7 @@
 // limitations under the License.

 use super::*;
+use frame_support_procedural::import_section;
 use sp_io::{MultiRemovalResults, TestExternalities};
 use sp_metadata_ir::{
 	PalletStorageMetadataIR, StorageEntryMetadataIR, StorageEntryModifierIR, StorageEntryTypeIR,
@@ -27,13 +28,15 @@ pub use self::frame_system::{pallet_prelude::*, Config, Pallet};

 mod inject_runtime_type;
 mod storage_alias;
+mod tasks;

+#[import_section(tasks::tasks_example)]
 #[pallet]
 pub mod frame_system {
 	#[allow(unused)]
 	use super::{frame_system, frame_system::pallet_prelude::*};
 	pub use crate::dispatch::RawOrigin;
-	use crate::pallet_prelude::*;
+	use crate::{pallet_prelude::*, traits::tasks::Task as TaskTrait};

 	pub mod config_preludes {
 		use super::{inject_runtime_type, DefaultConfig};
@@ -49,6 +52,8 @@ pub mod frame_system {
 			type RuntimeCall = ();
 			#[inject_runtime_type]
 			type PalletInfo = ();
+			#[inject_runtime_type]
+			type RuntimeTask = ();
 			type DbWeight = ();
 		}
 	}
@@ -69,6 +74,8 @@ pub mod frame_system {
 		#[pallet::no_default_bounds]
 		type RuntimeCall;
 		#[pallet::no_default_bounds]
+		type RuntimeTask: crate::traits::tasks::Task;
+		#[pallet::no_default_bounds]
 		type PalletInfo: crate::traits::PalletInfo;
 		type DbWeight: Get<crate::weights::RuntimeDbWeight>;
 	}
@@ -77,13 +84,33 @@ pub mod frame_system {
 	pub enum Error<T> {
 		/// Required by construct_runtime
 		CallFiltered,
+		/// Used in tasks example.
+		NotFound,
+		/// The specified [`Task`] is not valid.
+		InvalidTask,
+		/// The specified [`Task`] failed during execution.
+		FailedTask,
 	}

 	#[pallet::origin]
 	pub type Origin<T> = RawOrigin<<T as Config>::AccountId>;

 	#[pallet::call]
-	impl<T: Config> Pallet<T> {}
+	impl<T: Config> Pallet<T> {
+		#[pallet::call_index(0)]
+		#[pallet::weight(task.weight())]
+		pub fn do_task(_origin: OriginFor<T>, task: T::RuntimeTask) -> DispatchResultWithPostInfo {
+			if !task.is_valid() {
+				return Err(Error::<T>::InvalidTask.into())
+			}
+
+			if let Err(_err) = task.run() {
+				return Err(Error::<T>::FailedTask.into())
+			}
+
+			Ok(().into())
+		}
+	}

 	#[pallet::storage]
 	pub type Data<T> = StorageMap<_, Twox64Concat, u32, u64, ValueQuery>;
@@ -169,6 +196,14 @@ pub mod frame_system {
 		}
 	}

+	/// Some running total.
+	#[pallet::storage]
+	pub type Total<T: Config> = StorageValue<_, (u32, u32), ValueQuery>;
+
+	/// Numbers to be added into the total.
+	#[pallet::storage]
+	pub type Numbers<T: Config> = StorageMap<_, Twox64Concat, u32, u32, OptionQuery>;
+
 	pub mod pallet_prelude {
 		pub type OriginFor<T> = <T as super::Config>::RuntimeOrigin;

@@ -622,6 +657,24 @@ fn expected_metadata() -> PalletStorageMetadataIR {
 				default: vec![0],
 				docs: vec![],
 			},
+			StorageEntryMetadataIR {
+				name: "Total",
+				modifier: StorageEntryModifierIR::Default,
+				ty: StorageEntryTypeIR::Plain(scale_info::meta_type::<(u32, u32)>()),
+				default: vec![0, 0, 0, 0, 0, 0, 0, 0],
+				docs: vec![" Some running total."],
+			},
+			StorageEntryMetadataIR {
+				name: "Numbers",
+				modifier: StorageEntryModifierIR::Optional,
+				ty: StorageEntryTypeIR::Map {
+					hashers: vec![StorageHasherIR::Twox64Concat],
+					key: scale_info::meta_type::<u32>(),
+					value: scale_info::meta_type::<u32>(),
+				},
+				default: vec![0],
+				docs: vec![" Numbers to be added into the total."],
+			},
 		],
 	}
 }
@@ -0,0 +1,62 @@
+// This file is part of Substrate.
+
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use crate::{
+	assert_ok,
+	tests::{
+		frame_system::{Numbers, Total},
+		new_test_ext, Runtime, RuntimeOrigin, RuntimeTask, System,
+	},
+};
+use frame_support_procedural::pallet_section;
+
+#[pallet_section]
+mod tasks_example {
+	#[docify::export(tasks_example)]
+	#[pallet::tasks_experimental]
+	impl<T: Config> Pallet<T> {
+		/// Add a pair of numbers into the totals and remove them.
+		#[pallet::task_list(Numbers::<T>::iter_keys())]
+		#[pallet::task_condition(|i| Numbers::<T>::contains_key(i))]
+		#[pallet::task_weight(0.into())]
+		#[pallet::task_index(0)]
+		pub fn add_number_into_total(i: u32) -> DispatchResult {
+			let v = Numbers::<T>::take(i).ok_or(Error::<T>::NotFound)?;
+			Total::<T>::mutate(|(total_keys, total_values)| {
+				*total_keys += i;
+				*total_values += v;
+			});
+			Ok(())
+		}
+	}
+}
+
+#[docify::export]
+#[test]
+fn tasks_work() {
+	new_test_ext().execute_with(|| {
+		Numbers::<Runtime>::insert(0, 1);
+
+		let task = RuntimeTask::System(super::frame_system::Task::<Runtime>::AddNumberIntoTotal {
+			i: 0u32,
+		});
+
+		assert_ok!(System::do_task(RuntimeOrigin::signed(1), task.clone(),));
+		assert_eq!(Numbers::<Runtime>::get(0), None);
+		assert_eq!(Total::<Runtime>::get(), (0, 1));
+	});
+}
@@ -123,6 +123,9 @@ pub use safe_mode::{SafeMode, SafeModeError, SafeModeNotify};
 mod tx_pause;
 pub use tx_pause::{TransactionPause, TransactionPauseError};

+pub mod tasks;
+pub use tasks::Task;
+
 #[cfg(feature = "try-runtime")]
 mod try_runtime;
 #[cfg(feature = "try-runtime")]
@@ -0,0 +1,87 @@
+// This file is part of Substrate.
+
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//! Contains the [`Task`] trait, which defines a general-purpose way for defining and executing
+//! service work, and supporting types.
+
+use codec::FullCodec;
+use scale_info::TypeInfo;
+use sp_runtime::DispatchError;
+use sp_std::{fmt::Debug, iter::Iterator, vec, vec::IntoIter};
+use sp_weights::Weight;
+
+/// Contain's re-exports of all the supporting types for the [`Task`] trait. Used in the macro
+/// expansion of `RuntimeTask`.
+#[doc(hidden)]
+pub mod __private {
+	pub use codec::FullCodec;
+	pub use scale_info::TypeInfo;
+	pub use sp_runtime::DispatchError;
+	pub use sp_std::{fmt::Debug, iter::Iterator, vec, vec::IntoIter};
+	pub use sp_weights::Weight;
+}
+
+/// A general-purpose trait which defines a type of service work (i.e., work to performed by an
+/// off-chain worker) including methods for enumerating, validating, indexing, and running
+/// tasks of this type.
+pub trait Task: Sized + FullCodec + TypeInfo + Clone + Debug + PartialEq + Eq {
+	/// An [`Iterator`] over tasks of this type used as the return type for `enumerate`.
+	type Enumeration: Iterator;
+
+	/// Inspects the pallet's state and enumerates tasks of this type.
+	fn iter() -> Self::Enumeration;
+
+	/// Checks if a particular instance of this `Task` variant is a valid piece of work.
+	fn is_valid(&self) -> bool;
+
+	/// Performs the work for this particular `Task` variant.
+	fn run(&self) -> Result<(), DispatchError>;
+
+	/// Returns the weight of executing this `Task`.
+	fn weight(&self) -> Weight;
+
+	/// A unique value representing this `Task` within the current pallet. Analogous to
+	/// `call_index`, but for tasks.'
+	///
+	/// This value should be unique within the current pallet and can overlap with task indices
+	/// in other pallets.
+	fn task_index(&self) -> u32;
+}
+
+impl Task for () {
+	type Enumeration = IntoIter<Self>;
+
+	fn iter() -> Self::Enumeration {
+		vec![].into_iter()
+	}
+
+	fn is_valid(&self) -> bool {
+		true
+	}
+
+	fn run(&self) -> Result<(), DispatchError> {
+		Ok(())
+	}
+
+	fn weight(&self) -> Weight {
+		Weight::default()
+	}
+
+	fn task_index(&self) -> u32 {
+		0
+	}
+}