Expand description
Made with Substrate, for 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
- 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)]);
});
}
- 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.
- Could fail due to the runtime call index not being part of the
Re-exports§
pub use weights::WeightInfo;
pub use pallet::*;
Modules§
- Migrations for the scheduler pallet.
- The
pallet
module in each FRAME pallet hosts the most important items needed to construct this pallet. - Autogenerated weights for
pallet_scheduler
Structs§
- The configuration of the retry mechanism for a given task along with its current state.
- Information regarding an item to be executed in the future.
Type Aliases§
- Just a simple index for naming period tasks.
- The location of a scheduled task that can be used to remove it.