Periodic tasks and timers
Unlike other blockchains, the Internet Computer can automatically execute canister smart contracts after a specified delay or periodically.
There are two ways to schedule an automatic canister execution on the IC:
- Timers: single-expiration or periodic canister calls with specified minimum timeout or interval.
- Heartbeats: legacy periodic canister invocations with intervals close to the blockchain finalization rate (1s). Heartbeats are supported by the IC for backward compatibility and some very special use cases. Newly developed canisters should prefer using timers over the heartbeats.
Timers are implemented on two layers:
- The protocol level implementation: the Internet Computer protocol supports minimalistic on-shot global timer per canister via
ic0.global_timer_set()system API call and
canister_global_timerhandler (see the Internet Computer interface specification).
- The CDK timers library level: the library wraps the minimalistic protocol implementation, adding multiple and periodic timers on top. Canister developers can enjoy the familiar timers functionality using the CDK timers library for Rust or Motoko.
Internally the CDK timers library does the following:
- The library keeps a global list of multiple and periodic tasks inside the canister.
- Calls the
ic0.global_timer_set()system API to schedule the next task from the list.
- Implements the
canister_global_timermethod with the following logic:
- For each expired task, the handler initiates a self canister call to isolate the tasks from each other and from the library code. Note, the normal inter-canister call costs costs apply.
- Reschedules periodic tasks at the end of their execution.
- Calls the
ic0.global_timer_set()system API to schedule the next task.
The library does not handle the canister upgrades. It is up to the canister developer to serialize the timers in the
canister_pre_upgrade and reactivate the timers in the
canister_post_upgrade method if needed.
For the code composability reasons, i.e. to be able to use different libraries with timers in a single project, canister developers are encouraged to use the CDK timers library over the protocol level API or the heartbeats.
Timers library limitations
Despite its superiority over the heartbeats, the CDK timers library has a few known shortcomings:
- Canister upgrades: the library keeps a global list of multiple and periodic tasks inside the canister heap. During the canister upgrade, a fresh WebAssembly state is created, all the timers are deactivated and the list of timers is cleared. It is up to the canister developer to serialize the timers in the
canister_pre_upgradeand reactivate them in the
canister_post_upgrademethod if needed.
- Self canister calls: to isolate the tasks from each other and from the scheduling logic, CDK timers library initiates a self canister call to execute each task. There are a few implications:
- Normal inter-canister call costs apply to execute each task. Note, timers are still more cost effective than the heartbeats.
- The tasks to execute are added at the end of the canister input queue. Depending on the canister and subnet load, the actual execution might be delayed.
- As the canister output queue is limited in size (500 messages at the moment), this implicitly limits the number of tasks which might be scheduled in one round.
- Advanced scheduling: the CDK timers library uses relative time to schedule tasks. To use an absolute time, canister developers should calculate the duration between now and the point in time, or use a third party library.
Once an Internet Computer canister exports the
canister_heartbeat function, it will be called every subnet heartbeat interval (see the Internet Computer interface specification).
The only way to disable the heartbeats is to upgrade the canister to a version which does not export the
canister_heartbeat method. Also, the heartbeat interval is implementation-defined, and there is no way to adjust it.
Frequently asked questions
Do timers support deterministic time slicing (DTS)?
Yes, as the CDK timers library initiates a self canister call to execute each task, normal update message instruction limits apply with DTS enabled.
What happens if a timer handler awaits for a call?
Normal await point rules apply: any new execution can start at the await point: a new message, another timer handler or a heartbeat. Once that new execution is finished or reached its await point, the execution of the current timer handler might be resumed.
What happens if a 1s periodic timer is executing for 2s?
If there are no await points in the timer handler, the periodic timer will be rescheduled at the end of the execution. If there are await points, it's implementation-defined when the periodic timer is rescheduled.