From 39010a506cdc87a2f4f64eb7c4cafeee645967d9 Mon Sep 17 00:00:00 2001 From: Ryan Vandersmith Date: Thu, 23 Jan 2025 15:18:04 -0700 Subject: [PATCH 1/5] Update `Timer` module doc comments --- src/Timer.mo | 37 ++++++++++++++++++------------------- 1 file changed, 18 insertions(+), 19 deletions(-) diff --git a/src/Timer.mo b/src/Timer.mo index c9b7be16..39d89343 100644 --- a/src/Timer.mo +++ b/src/Timer.mo @@ -1,26 +1,25 @@ /// Timers for one-off or periodic tasks. Applicable as part of the default mechanism. +/// If `moc` is invoked with `-no-timer`, the importing will fail. /// -/// Note: If `moc` is invoked with `-no-timer`, the importing will fail. +/// The resolution of the timers is similar to the block rate, +/// so durations should be chosen well above that. For frequent +/// canister wake-ups, consider using the [heartbeat](https://internetcomputer.org/docs/current/motoko/main/writing-motoko/heartbeats) mechanism. /// -/// Note: The resolution of the timers is in the order of the block rate, -/// so durations should be chosen well above that. For frequent -/// canister wake-ups the heartbeat mechanism should be considered. +/// The functionality described below is enabled only when the actor does not override it by declaring an explicit `system func timer`. /// -/// Note: The functionality described below is enabled only when the actor does not override it by declaring an explicit `system func timer`. +/// Timers are _not_ persisted across upgrades. One possible strategy +/// to re-establish timers after an upgrade is to walk stable variables +/// in the `post_upgrade` hook and distill necessary timer information +/// from there. /// -/// Note: Timers are _not_ persisted across upgrades. One possible strategy -/// to re-establish timers after an upgrade is to walk stable variables -/// in the `post_upgrade` hook and distill necessary timer information -/// from there. +/// Using timers for security (e.g. access control) is strongly discouraged. +/// Make sure to inform yourself about state-of-the art dApp security. +/// If you must use timers for security controls, be sure +/// to consider reentrancy issues as well as the vanishing of timers on upgrades +/// and reinstalls. /// -/// Note: Basing security (e.g. access control) on timers is almost always -/// the wrong choice. Be sure to inform yourself about state-of-the art -/// dApp security. If you _must use_ timers for security controls, be sure -/// to consider reentrancy issues, and the vanishing of timers on upgrades -/// and reinstalls. -/// -/// Note: For further usage information for timers on the IC please consult -/// https://internetcomputer.org/docs/current/developer-docs/backend/periodic-tasks#timers-library-limitations +/// For further usage information for timers on the IC please consult +/// [the documentation](https://internetcomputer.org/docs/current/developer-docs/backend/periodic-tasks#timers-library-limitations). import { setTimer = setTimerNano; cancelTimer = cancel } = "mo:⛔"; import { fromIntWrap } = "Nat64"; @@ -68,8 +67,8 @@ module { /// and not recognised `id`s nothing happens. /// /// ```motoko no-repl - /// func deleteAppt(appt : Appointment) { - /// cancelTimer (appt.reminder); + /// func deleteAppointment(appointment : Appointment) { + /// cancelTimer (appointment.reminder); /// // ... /// }; /// ``` From 57f0c6dcebcf94224d0a7e15bbc8e9052897671e Mon Sep 17 00:00:00 2001 From: Ryan Vandersmith Date: Thu, 23 Jan 2025 15:30:51 -0700 Subject: [PATCH 2/5] Apply suggestions from code review Co-authored-by: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> --- src/Timer.mo | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/Timer.mo b/src/Timer.mo index 39d89343..272ba1dd 100644 --- a/src/Timer.mo +++ b/src/Timer.mo @@ -3,7 +3,7 @@ /// /// The resolution of the timers is similar to the block rate, /// so durations should be chosen well above that. For frequent -/// canister wake-ups, consider using the [heartbeat](https://internetcomputer.org/docs/current/motoko/main/writing-motoko/heartbeats) mechanism. +/// canister wake-ups, consider using the [heartbeat](https://internetcomputer.org/docs/current/motoko/main/writing-motoko/heartbeats) mechanism; however, when possible, canisters should prefer timers. /// /// The functionality described below is enabled only when the actor does not override it by declaring an explicit `system func timer`. /// @@ -12,13 +12,13 @@ /// in the `post_upgrade` hook and distill necessary timer information /// from there. /// -/// Using timers for security (e.g. access control) is strongly discouraged. -/// Make sure to inform yourself about state-of-the art dApp security. +/// Using timers for security (e.g., access control) is strongly discouraged. +/// Make sure to inform yourself about state-of-the-art dapp security. /// If you must use timers for security controls, be sure /// to consider reentrancy issues as well as the vanishing of timers on upgrades /// and reinstalls. /// -/// For further usage information for timers on the IC please consult +/// For further usage information for timers on the IC, please consult /// [the documentation](https://internetcomputer.org/docs/current/developer-docs/backend/periodic-tasks#timers-library-limitations). import { setTimer = setTimerNano; cancelTimer = cancel } = "mo:⛔"; import { fromIntWrap } = "Nat64"; From c79a5c142f94330b60dc21c62be31db4c047721d Mon Sep 17 00:00:00 2001 From: Ryan Vandersmith Date: Thu, 23 Jan 2025 15:31:17 -0700 Subject: [PATCH 3/5] Update src/Timer.mo Co-authored-by: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> --- src/Timer.mo | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Timer.mo b/src/Timer.mo index 272ba1dd..fd89979e 100644 --- a/src/Timer.mo +++ b/src/Timer.mo @@ -8,7 +8,7 @@ /// The functionality described below is enabled only when the actor does not override it by declaring an explicit `system func timer`. /// /// Timers are _not_ persisted across upgrades. One possible strategy -/// to re-establish timers after an upgrade is to walk stable variables +/// to re-establish timers after an upgrade is to use stable variables /// in the `post_upgrade` hook and distill necessary timer information /// from there. /// From 71baf7015e32eae6e2acb439241bfcfe9edb8aa7 Mon Sep 17 00:00:00 2001 From: Ryan Vandersmith Date: Tue, 28 Jan 2025 08:45:50 -0700 Subject: [PATCH 4/5] Update src/Timer.mo Co-authored-by: Gabor Greif --- src/Timer.mo | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Timer.mo b/src/Timer.mo index fd89979e..2bf97b66 100644 --- a/src/Timer.mo +++ b/src/Timer.mo @@ -1,5 +1,5 @@ /// Timers for one-off or periodic tasks. Applicable as part of the default mechanism. -/// If `moc` is invoked with `-no-timer`, the importing will fail. +/// If `moc` is invoked with `-no-timer`, the importing will fail. Furthermore if passed `--trap-on-call-error` a congested canister send queue may prevent timer expirations to execute at runtime, and also may deactivate the global timer. /// /// The resolution of the timers is similar to the block rate, /// so durations should be chosen well above that. For frequent From 6c5de266b1b90d11983404241e3fde4eb5970186 Mon Sep 17 00:00:00 2001 From: rvanasa Date: Tue, 28 Jan 2025 08:48:13 -0700 Subject: [PATCH 5/5] Adjust wording --- src/Timer.mo | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Timer.mo b/src/Timer.mo index 2bf97b66..438ea35a 100644 --- a/src/Timer.mo +++ b/src/Timer.mo @@ -1,5 +1,5 @@ /// Timers for one-off or periodic tasks. Applicable as part of the default mechanism. -/// If `moc` is invoked with `-no-timer`, the importing will fail. Furthermore if passed `--trap-on-call-error` a congested canister send queue may prevent timer expirations to execute at runtime, and also may deactivate the global timer. +/// If `moc` is invoked with `-no-timer`, the importing will fail. Furthermore, if passed `--trap-on-call-error`, a congested canister send queue may prevent timer expirations to execute at runtime. It may also deactivate the global timer. /// /// The resolution of the timers is similar to the block rate, /// so durations should be chosen well above that. For frequent