chore: update Timer.md with caveats (#3827)

* Update Timer.md * Update doc/md/base/Timer.md Co-authored-by: Claudio Russo <[email protected]> * Update doc/md/base/Timer.md Co-authored-by: Claudio Russo <[email protected]> * mention reentrancy * point to timer FAQ --------- Co-authored-by: Claudio Russo <[email protected]>
dfinity · Dec 4, 2024 · eb3cbd3 · eb3cbd3
1 parent 6603c0a
commit eb3cbd3
Showing 1 changed file with 20 additions and 2 deletions.
diff --git a/doc/md/base/Timer.md b/doc/md/base/Timer.md
@@ -1,10 +1,28 @@
 # Timer
-Timers for one-off or periodic tasks.
+
+Timers for one-off or periodic tasks. Applicable as part of the default mechanism.
 
 Note: If `moc` is invoked with `-no-timer`, the importing will fail.
+
 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 heatbeat mechanism should be considered.
+      canister wake-ups the heartbeat mechanism should be considered.
+
+Note: The functionality described below is enabled only when the actor does not override it by declaring an explicit `system func timer`.
+
+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.
+
+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
 
 ## Type `Duration`
 ``` motoko no-repl