Crate pallet_scheduler

source ·
Expand description

Made with Substrate, for Polkadot.

github - polkadot

§Scheduler Pallet

A Pallet for scheduling runtime calls.

§Overview

This Pallet exposes capabilities for scheduling runtime calls to occur at a specified block number or at a specified period. These scheduled runtime calls may be named or anonymous and may be canceled.

NOTE: Instead of using the filter contained in the origin to call fn schedule, scheduled runtime calls will be dispatched with the default filter for the origin: namely frame_system::Config::BaseCallFilter for all origin types (except root which will get no filter).

If a call is scheduled using proxy or whatever mechanism which adds filter, then those filter will not be used when dispatching the schedule runtime call.

§Examples

  1. Scheduling a runtime call at a specific block.
ⓘ
#[test]
fn basic_scheduling_works() {
	new_test_ext().execute_with(|| {
		// Call to schedule
		let call =
			RuntimeCall::Logger(LoggerCall::log { i: 42, weight: Weight::from_parts(10, 0) });

		// BaseCallFilter should be implemented to accept `Logger::log` runtime call which is
		// implemented for `BaseFilter` in the mock runtime
		assert!(!<Test as frame_system::Config>::BaseCallFilter::contains(&call));

		// Schedule call to be executed at the 4th block
		assert_ok!(Scheduler::do_schedule(
			DispatchTime::At(4),
			None,
			127,
			root(),
			Preimage::bound(call).unwrap()
		));

		// `log` runtime call should not have executed yet
		run_to_block(3);
		assert!(logger::log().is_empty());

		run_to_block(4);
		// `log` runtime call should have executed at block 4
		assert_eq!(logger::log(), vec![(root(), 42u32)]);

		run_to_block(100);
		assert_eq!(logger::log(), vec![(root(), 42u32)]);
	});
}
  1. Scheduling a preimage hash of a runtime call at a specific block
ⓘ
#[test]
fn scheduling_with_preimages_works() {
	new_test_ext().execute_with(|| {
		// Call to schedule
		let call =
			RuntimeCall::Logger(LoggerCall::log { i: 42, weight: Weight::from_parts(10, 0) });

		let hash = <Test as frame_system::Config>::Hashing::hash_of(&call);
		let len = call.using_encoded(|x| x.len()) as u32;

		// Important to use here `Bounded::Lookup` to ensure that that the Scheduler can request the
		// hash from PreImage to dispatch the call
		let hashed = Bounded::Lookup { hash, len };

		// Schedule call to be executed at block 4 with the PreImage hash
		assert_ok!(Scheduler::do_schedule(DispatchTime::At(4), None, 127, root(), hashed));

		// Register preimage on chain
		assert_ok!(Preimage::note_preimage(RuntimeOrigin::signed(0), call.encode()));
		assert!(Preimage::is_requested(&hash));

		// `log` runtime call should not have executed yet
		run_to_block(3);
		assert!(logger::log().is_empty());

		run_to_block(4);
		// preimage should not have been removed when executed by the scheduler
		assert!(!Preimage::len(&hash).is_some());
		assert!(!Preimage::is_requested(&hash));
		// `log` runtime call should have executed at block 4
		assert_eq!(logger::log(), vec![(root(), 42u32)]);

		run_to_block(100);
		assert_eq!(logger::log(), vec![(root(), 42u32)]);
	});
}

§Pallet API

See the pallet module for more information about the interfaces this pallet exposes, including its configuration trait, dispatchables, storage items, events and errors.

§Warning

This Pallet executes all scheduled runtime calls in the on_initialize hook. Do not execute any runtime calls which should not be considered mandatory.

Please be aware that any scheduled runtime calls executed in a future block may fail or may result in undefined behavior since the runtime could have upgraded between the time of scheduling and execution. For example, the runtime upgrade could have:

  • Modified the implementation of the runtime call (runtime specification upgrade).
    • Could lead to undefined behavior.
  • Removed or changed the ordering/index of the runtime call.
    • Could fail due to the runtime call index not being part of the Call.
    • Could lead to undefined behavior, such as executing another runtime call with the same index.

Re-exports§

Modules§

  • migration
    Migrations for the scheduler pallet.
  • pallet
    The pallet module in each FRAME pallet hosts the most important items needed to construct this pallet.
  • weights
    Autogenerated weights for pallet_scheduler

Structs§

  • RetryConfig
    The configuration of the retry mechanism for a given task along with its current state.
  • Scheduled
    Information regarding an item to be executed in the future.

Type Aliases§