feat: parenthetical syntax for message sends (cycles, timeout etc.) (#4608)

This PR introduces new syntax (parenthetical notes, or simply _parentheticals_) for `async`-valued calls and `async` self-sends. Two attributes are recognised therein: `cycles : Nat` and `timeout : Nat32`. The type-checker enforces these types (when attributes present) and warns on unknown ones. Having a `timeout` attribute present will make the message send a bounded-wait one (also called best-effort) according to the new replica semantics. Specifying `cycles` works like the (soon to be deprecated) `Cycles.add<system>`, ~but one has to decide which to use (either `Cycles.add` or a parenthetical) since there is no mix-and-match~.


-----------
~`ICCallPrim` (and friends) should carry the fragment to set the `SystemCyclesAddPrim` while the call is being set up towards the replica.~ This now happens in the desugarer by assigning to variables (`@cycles` and `@timeout`).

Parentheticals
- now: `(with cycles = 42_000_000) Actor.call(param)`
- also now: `(with timeout = 10)`
  `ic0.call_with_best_effort_response : (timeout_seconds : i32) -> ()`
- maybe: `(with receiveMax = 50_000)` (to limit the response size)
- maybe: `(with resend = { tries = 5; delay = 3 })` when `SYS_UNKNOWN` reject response (like [Unix `EINTR`](https://unix.stackexchange.com/questions/253349/what-is-the-rationale-behind-eintr), but saves cycles by not re-encoding the arguments)
- support dfinity/ic#1158
- usecase `(with memoryLimit = 1G) ActorClass(<args>)`
- default/suppress call-meta-attributes: `func() : async () = (with) async { ... }` — document this!

TODOs:
- [x] `Changelog.md`
- [x] documentation
- [x] test one-ways
- typecheck
  - [x] warn when an attribute is moot
  - [x] `cycles : Nat` for canister sends (_self_ and _raw_ sends too)
  - [x] `timeout : Nat32` for best-effort
  - [x] parenthetical should have no send cap (test still missing)
- [x] `async` blocks
- [x] `ICCallPrim`, see top
- `ICCallRawPrim`, not directly annotatable (desisting for now, but see #4868)
- [ ] `FIXME`s, `TODO`s
  - [x] `ICCallPrim` should have a non-`option` setup
  - [ ] break out unrelated PRs (optimisations?) and beautifications — see #4890
- [ ] warn on queries?
- [x] best-effort: new error code when deadline passed?
  - [x] doc/md/base/Error.md -> `motoko-base`, see dfinity/motoko-base#686
  - [x] visit all `git grep system_fatal` and amend `#system_unknown`
- [x] decide whether `(with cycles) async` or `async (with cycles)` — decided: keep as prefix!
- [x] write a temporary test that `Cycles.add` still works
- [x] test that parenthetical have no send capability
- [x] test `(with cycles) (func () -> async () {})()` direct application
- [x] test `(with cycles) (system Lib.Class)(...)()`
- [x] test error on `async*` (and call)

Author: ggreif

Changelog.md

@@ -1,9 +1,25 @@
 # Motoko compiler changelog
 
+## 0.14.2 (FUTURE)
+
 * motoko (`moc`)
 
-  * bugfix: `mo-doc` will now generate documentation for `actor`s and `actor class`es (#4905).
+  * Added support for sending `cycles` and setting a `timeout` in parentheticals.
+    This is an **experimental feature**, with new syntax, and now also allowing best-effort
+    message sends. The legacy call `Cycles.add<system>` is still supported (#4608).
+
+    For example, if one wants to attach cycles to a message send, prefix it with a parenthetical
+    ``` motoko
+    (with cycles = 5_000) Coins.mine(forMe);
+    ```
+    Similarly a timeout for _best-effort_ execution (also called _bounded-wait_) can be specified like
+    ``` motoko
+    let worker = (with timeout = 15) async { /* worker loop */ };
+    ```
+    A common base for fields optionally goes before the `with` and can be customised with both fields
+    after it. Please consult the documentation for more usage information.
 
+  * bugfix: `mo-doc` will now generate documentation for `actor`s and `actor class`es (#4905).
 
 ## 0.14.1 (2025-02-13)
 
@@ -22,7 +38,7 @@
     Additional static checks warn against possible data loss (#4812).
 
     As a very simple example:
-    ```
+    ``` motoko
     import Nat32 "mo:base/Nat32";
 
     (with migration =

doc/md/canister-maintenance/cycles.md

@@ -13,11 +13,14 @@ In Motoko programs deployed on ICP, each actor represents a canister and has an
 
 Callees can accept all, some, or none of the available cycles up to limit determined by their actor’s current balance. Any remaining cycles are refunded to the caller. If a call traps, all its accompanying cycles are automatically refunded to the caller without loss.
 
-In future, we may see Motoko adopt dedicated syntax and types to support safer programming with cycles. For now, we provide a temporary way to manage cycles through a low-level imperative API provided by the [ExperimentalCycles](../base/ExperimentalCycles.md) library in package `base`.
+Motoko is adopting dedicated syntax and types to support safer programming with cycles. Users can now attach `(where cycles = <amount>)` as a prefix to message sends and async expressions.
+This new syntax will eventually obsolete the use of `ExperimentalCycles.add<system>(cycles)` in the examples that follow.
+
+For now (and until officially deprecating it), we provide a temporary way to manage cycles through a low-level imperative API provided by the [ExperimentalCycles](../base/ExperimentalCycles.md) library in package `base`.
 
 :::note
 
-This library is subject to change and likely to be replaced by more high-level support for cycles in later versions of Motoko.
+This library is subject to change and likely to be replaced by more high-level support for cycles in later versions of Motoko. See [Async data](../writing-motoko/async-data.md) for further usage information about parentheticals (such as attaching cycles) on message sends.
 
 :::
 

doc/md/examples/PiggyBank.mo

@@ -29,8 +29,7 @@ shared(msg) persistent actor class PiggyBank(
     : async () {
     assert (msg.caller == owner);
     assert (amount <= savings);
-    Cycles.add<system>(amount);
-    await benefit();
+    await (with cyles = amount) benefit();
     let refund = Cycles.refunded();
     savings -= amount - refund;
   };

doc/md/examples/grammar.txt

@@ -188,6 +188,7 @@
 
 <exp_un> ::= 
     <exp_post>
+    <parenthetical> <exp_post> <inst> <exp_nullary>
     '#' <id>
     '#' <id> <exp_nullary>
     '?' <exp_un>
@@ -213,7 +214,7 @@
     <exp_bin> ':=' <exp>
     <exp_bin> <binassign> <exp>
     'return' <exp>?
-    'async' <exp_nest>
+    <parenthetical>? 'async' <exp_nest>
     'async*' <exp_nest>
     'await' <exp_nest>
     'await*' <exp_nest>

doc/md/reference/language-manual.md

@@ -507,7 +507,7 @@ The syntax of an expression is as follows:
   [ var? <exp>,* ]                               Array
   <exp> [ <exp> ]                                Array indexing
   <shared-pat>? func <func_exp>                  Function expression
-  <exp> <typ-args>? <exp>                        Function call
+  <parenthetical>? <exp> <typ-args>? <exp>       Function call
   not <exp>                                      Negation
   <exp> and <exp>                                Conjunction
   <exp> or <exp>                                 Disjunction
@@ -520,7 +520,7 @@ The syntax of an expression is as follows:
   break <id> <exp>?                              Break
   continue <id>                                  Continue
   return <exp>?                                  Return
-  async <block-or-exp>                           Async expression
+  <parenthetical>? async <block-or-exp>          Async expression
   await <block-or-exp>                           Await future (only in async)
   async* <block-or-exp>                          Delay an asynchronous computation
   await* <block-or-exp>                          Await a delayed computation (only in async)
@@ -746,6 +746,8 @@ type ErrorCode = {
   #system_fatal;
   // Transient error.
   #system_transient;
+  // Response unknown due to missed deadline.
+  #system_unknown;
   // Destination invalid.
   #destination_invalid;
   // Explicit reject by canister code.
@@ -2188,7 +2190,7 @@ Otherwise,
 
 ### Function calls
 
-The function call expression `<exp1> <T0,…​,Tn>? <exp2>` has type `T` provided:
+The function call expression `<parenthetical>? <exp1> <T0,…​,Tn>? <exp2>` has type `T` provided:
 
 -   The function `<exp1>` has function type `<shared>? < X0 <: V0, ..., Xn <: Vn > U1-> U2`.
 
@@ -2206,6 +2208,10 @@ Otherwise, `exp2` is evaluated to a result `r2`. If `r2` is `trap`, the expressi
 
 Otherwise, `r1` is a function value, `<shared-pat>? func <X0 <: V0, …​, n <: Vn> <pat1> { <exp> }` (for some implicit environment), and `r2` is a value `v2`. If `<shared-pat>` is present and of the form `shared <query>? <pat>` then evaluation continues by matching the record value `{caller = p}` against `<pat>`, where `p` is the [`Principal`](../base/Principal.md) invoking the function, typically a user or canister. Matching continues by matching `v1` against `<pat1>`. If pattern matching succeeds with some bindings, then evaluation returns the result of `<exp>` in the environment of the function value not shown extended with those bindings. Otherwise, some pattern match has failed and the call results in `trap`.
 
+A `<parenthetical>`, when present, modifies dynamic attributes of the message send (provided that the return type `T` is of form `async U`, i.e. a future). The recognized attributes are
+- `cycles : Nat` to attach cycles
+- `timeout : Nat32` to introduce a timeout for best-effort message execution.
+
 :::note
 
 The exhaustiveness side condition on `shared` function expressions ensures that argument pattern matching cannot fail (see [functions](#functions)).
@@ -2478,7 +2484,7 @@ The `return` expression exits the corresponding dynamic function invocation or c
 
 ### Async
 
-The async expression `async <block-or-exp>` has type `async T` provided:
+The async expression `<parenthetical>? async <block-or-exp>` has type `async T` provided:
 
 -   `<block-or-exp>` has type `T`.
 
@@ -2490,6 +2496,10 @@ The implicit return type in `<block-or-exp>` is `T`. That is, the return express
 
 Evaluation of `async <block-or-exp>` queues a message to evaluate `<block-or-exp>` in the nearest enclosing or top-level actor. It immediately returns a future of type `async T` that can be used to `await` the result of the pending evaluation of `<exp>`.
 
+The presence of `<parenthetical>` modifies the semantics of the async expression to
+- attach cycles with attribute `cycles : Nat`
+- impose a timeout (observed when awaiting the result) with attribute `timeout : Nat32`.
+
 :::note
 
 Because it involves messaging, evaluating an `async` expression can fail due to a lack of canister resources.
@@ -2788,4 +2798,4 @@ In general, this means that an expression of a more specific type may appear whe
 -   **IEEE Standard for Floating-Point Arithmetic**, in IEEE Std 754-2019 (Revision of IEEE 754-2008), vol., no., pp.1-84, 22 July 2019, doi: 10.1109/IEEESTD.2019.8766229.
 
 
-<img src="https://github.com/user-attachments/assets/844ca364-4d71-42b3-aaec-4a6c3509ee2e" alt="Logo" width="150" height="150" />
+<img src="https://github.com/user-attachments/assets/844ca364-4d71-42b3-aaec-4a6c3509ee2e" alt="Logo" width="150" height="150" />

doc/md/writing-motoko/async-data.md

@@ -14,6 +14,8 @@ Like several other languages, Motoko offers `async` and `await` to support conve
 In Motoko, executing an asynchronous expression, whether a call to a shared function, or just a local `async` expression, produces a future, an object of type `async T`, for some result type `T`.
 Instead of blocking the caller until the call has returned, the message is enqueued on the callee and the future representing that pending request is immediately returned to the caller. The future is a placeholder for the eventual result of the request that the caller can later query.
 
+Every operation resulting in a future (i.e. sends to other `actor`s/canisters or self sends with `async` or by function calls) can be prefixed by a _parenthetical_ of the form `(base with attr₁ = v₁; attr₂ = v₂; …)` where `base` is an optional record containing (e.g. default) attributes. Accepted attributes are currently `cycles : Nat`, specifying the amount of cycles to be sent along with the message, and `timeout : Nat32` to modify the deadline and restrict the time span while the receiver can reply.
+
 The syntax `await` synchronizes on a future, and suspends computation until the future is completed by its producer.
 
 Between issuing the request and deciding to wait for the result, the caller is free to do other work. Once the callee has processed the request, the future is completed and its result made available to the caller. If the caller is waiting on the future, its execution can resume with the result, otherwise the result is simply stored in the future for later use.
@@ -37,7 +39,6 @@ The `Counter` actor declares one field and three public, shared functions:
 
 -   Function `bump()` asynchronously increments and reads the counter.
 
-
 The only way to read or modify the state (`count`) of the `Counter` actor is through its shared functions.
 
 ## Using `await` to consume async futures
@@ -69,6 +70,25 @@ Unlike a local function call, which blocks the caller until the callee has retur
 
 Awaiting a future a second time will just produce the same result, including re-throwing any error stored in the future. Suspension occurs even if the future is already complete; this ensures state changes and message sends prior to every `await` are committed.
 
+## Using parentheticals to modify message send modalities
+
+In the above examples all messages sent to the `Counter` actor do not transmit cycles and will never timeout when their results are awaited. Both of these
+aspects can be configured by syntactically adding a parenthetical and thus modifying the dynamic attributes of the message send.
+
+To add cycles to the send one would write
+``` motoko no-repl
+let a = (with cycles = 42_000_000) Counter.bump();
+```
+Similarly, one can specify an explicit timeout to apply when awaiting the result of the message. This is useful in applications that prefer best-effort over guaranteed response message delivery:
+``` motoko no-repl
+let a = (with timeout = 25) Counter.bump();
+```
+Custom defaults for these attributes can be defined in a record that is used as the base expression of a parenthetical:
+``` motoko no-repl
+let boundedWait = { timeout = 25 };
+let a = (boundedWait with cycles = 42_000_000) Counter.bump();
+```
+
 :::danger
 
 A function that does not `await` in its body is guaranteed to execute atomically. In particular, the environment cannot change the state of the actor while the function is executing. If a function performs an `await`, however, atomicity is no longer guaranteed. Between suspension and resumption around the `await`, the state of the enclosing actor may change due to concurrent processing of other incoming actor messages. It is the programmer’s responsibility to guard against non-synchronized state changes. A programmer may, however, rely on any state change prior to the await being committed.
@@ -92,4 +112,4 @@ Each `await` suspends execution, allowing an interloper to change the state of t
 
 - [`rxmo`](https://mops.one/rxmo): A library for reactive programming using observables, making it easier to compose asynchronous or callback-based code.
 
-<img src="https://github.com/user-attachments/assets/844ca364-4d71-42b3-aaec-4a6c3509ee2e" alt="Logo" width="150" height="150" />
+<img src="https://github.com/user-attachments/assets/844ca364-4d71-42b3-aaec-4a6c3509ee2e" alt="Logo" width="150" height="150" />

src/codegen/compile_classical.ml

@@ -2519,10 +2519,13 @@ module Closure = struct
     Tagged.load_field env (Int32.add (header_size env) i)
 
   let store_data env i =
-    let (set_closure_data, get_closure_data) = new_local env "closure_data" in
-    set_closure_data ^^
-    Tagged.load_forwarding_pointer env ^^
-    get_closure_data ^^
+    (if !Flags.gc_strategy = Flags.Incremental then
+       let set_closure_data, get_closure_data = new_local env "closure_data" in
+       set_closure_data ^^
+       Tagged.load_forwarding_pointer env ^^
+       get_closure_data
+     else
+       G.nop) ^^
     Tagged.store_field env (Int32.add (header_size env) i)
 
   let prepare_closure_call env =
@@ -5056,6 +5059,7 @@ module IC = struct
       E.add_func_import env "ic0" "accept_message" [] [];
       E.add_func_import env "ic0" "call_data_append" (i32s 2) [];
       E.add_func_import env "ic0" "call_cycles_add128" (i64s 2) [];
+      E.add_func_import env "ic0" "call_with_best_effort_response" [I32Type] [];
       E.add_func_import env "ic0" "call_new" (i32s 8) [];
       E.add_func_import env "ic0" "call_perform" [] [I32Type];
       E.add_func_import env "ic0" "call_on_cleanup" (i32s 2) [];
@@ -5417,7 +5421,8 @@ module IC = struct
          "system_transient", 2l;
          "destination_invalid", 3l;
          "canister_reject", 4l;
-         "canister_error", 5l]
+         "canister_error", 5l;
+         "system_unknown", 6l]
         (Variant.inject env "future" (get_code ^^ BoxedSmallWord.box env Type.Nat32)))
 
   let error_message env =
@@ -9792,7 +9797,7 @@ module FuncDec = struct
       (fun get_cb_index ->
         get_cb_index ^^
         BoxedSmallWord.box env Type.Nat32 ^^
-        Serialization.serialize env Type.[Prim Nat32])
+        Serialization.serialize env Type.[nat32])
 
   let ic_call_one_shot env ts get_meth_pair get_arg add_cycles =
     match E.mode env with
@@ -9860,7 +9865,7 @@ module FuncDec = struct
         IC.assert_caller_self env ^^
 
         (* Deserialize and look up continuation argument *)
-        Serialization.deserialize env Type.[Prim Nat32] ^^
+        Serialization.deserialize env Type.[nat32] ^^
         BoxedSmallWord.unbox env Type.Nat32 ^^
         ContinuationTable.peek_future env ^^
         set_closure ^^
@@ -11308,7 +11313,7 @@ and compile_prim_invocation (env : E.t) ae p es at =
       compile_shl_const (Int32.of_int num_bits) ^^
       compile_shrS_const (Int32.of_int num_bits) ^^
       get_val ^^
-      compile_eq env Type.(Prim Nat32) ^^
+      compile_eq env Type.nat32 ^^
       E.else_trap_with env "losing precision" ^^
       get_val ^^
       compile_shl_const (Int32.of_int num_bits)
@@ -12149,6 +12154,7 @@ and compile_prim_invocation (env : E.t) ae p es at =
     compile_exp_vanilla env ae c ^^ set_c ^^
     FuncDec.ic_call env ts1 ts2 get_meth_pair get_arg get_k get_r get_c add_cycles
     end
+
   | ICCallRawPrim, [p;m;a;k;r;c] ->
     SR.unit, begin
     let set_meth_pair, get_meth_pair = new_local env "meth_pair" in
@@ -12207,6 +12213,9 @@ and compile_prim_invocation (env : E.t) ae p es at =
   | SystemCyclesBurnPrim, [e1] ->
     SR.Vanilla, compile_exp_vanilla env ae e1 ^^ Cycles.burn env
 
+  | SystemTimeoutSetPrim, [e1] ->
+    SR.unit, compile_exp_as env ae (SR.UnboxedWord32 Type.Nat32) e1 ^^ IC.system_call env "call_with_best_effort_response"
+
   | SetCertifiedData, [e1] ->
     SR.unit, compile_exp_vanilla env ae e1 ^^ IC.set_certified_data env
   | GetCertificate, [] ->
@@ -12516,7 +12525,7 @@ and compile_lit_pat env l =
   | Nat32Lit _ ->
     BoxedSmallWord.unbox env Type.Nat32 ^^
     compile_lit_as env (SR.UnboxedWord32 Type.Nat32) l ^^
-    compile_eq env Type.(Prim Nat32)
+    compile_eq env Type.nat32
   | Nat64Lit _ ->
     BoxedWord64.unbox env Type.Nat64 ^^
     compile_lit_as env (SR.UnboxedWord64 Type.Nat64) l ^^

src/codegen/compile_enhanced.ml

@@ -4716,6 +4716,7 @@ module IC = struct
       E.add_func_import env "ic0" "accept_message" [] [];
       E.add_func_import env "ic0" "call_data_append" (i64s 2) [];
       E.add_func_import env "ic0" "call_cycles_add128" (i64s 2) [];
+      E.add_func_import env "ic0" "call_with_best_effort_response" [I32Type] [];
       E.add_func_import env "ic0" "call_new" (i64s 8) [];
       E.add_func_import env "ic0" "call_perform" [] [I32Type];
       E.add_func_import env "ic0" "call_on_cleanup" (i64s 2) [];
@@ -5145,7 +5146,8 @@ module IC = struct
          "system_transient", 2L;
          "destination_invalid", 3L;
          "canister_reject", 4L;
-         "canister_error", 5L]
+         "canister_error", 5L;
+         "system_unknown", 6L]
         (Variant.inject env "future" (get_code ^^ BitTagged.tag env Type.Nat32)))
 
   let error_message env =
@@ -9639,7 +9641,7 @@ module FuncDec = struct
       (fun get_cb_index ->
         get_cb_index ^^
         TaggedSmallWord.msb_adjust Type.Nat32 ^^
-        Serialization.serialize env Type.[Prim Nat32])
+        Serialization.serialize env Type.[nat32])
 
   let ic_call_one_shot env ts get_meth_pair get_arg add_cycles =
     match E.mode env with
@@ -9708,7 +9710,7 @@ module FuncDec = struct
         IC.assert_caller_self env ^^
 
         (* Deserialize and look up continuation argument *)
-        Serialization.deserialize env Type.[Prim Nat32] ^^
+        Serialization.deserialize env Type.[nat32] ^^
         TaggedSmallWord.lsb_adjust Type.Nat32 ^^
         ContinuationTable.peek_future env ^^
         set_closure ^^
@@ -12274,6 +12276,7 @@ and compile_prim_invocation (env : E.t) ae p es at =
     compile_exp_vanilla env ae c ^^ set_c ^^
     FuncDec.ic_call env ts1 ts2 get_meth_pair get_arg get_k get_r get_c add_cycles
     end
+
   | ICCallRawPrim, [p;m;a;k;r;c] ->
     SR.unit, begin
     let set_meth_pair, get_meth_pair = new_local env "meth_pair" in
@@ -12320,6 +12323,13 @@ and compile_prim_invocation (env : E.t) ae p es at =
   | SystemCyclesBurnPrim, [e1] ->
     SR.Vanilla, compile_exp_vanilla env ae e1 ^^ Cycles.burn env
 
+  | SystemTimeoutSetPrim, [e1] ->
+    SR.unit,
+    compile_exp_as env ae (SR.UnboxedWord64 Type.Nat32) e1 ^^
+    TaggedSmallWord.lsb_adjust Type.Nat32 ^^
+    G.i (Convert (Wasm_exts.Values.I32 I32Op.WrapI64)) ^^
+    IC.system_call env "call_with_best_effort_response"
+
   | SetCertifiedData, [e1] ->
     SR.unit, compile_exp_vanilla env ae e1 ^^ IC.set_certified_data env
   | GetCertificate, [] ->
@@ -12632,7 +12642,7 @@ and compile_lit_pat env l =
     compile_eq env Type.(Prim Nat16)
   | Nat32Lit _ ->
     compile_lit_as env SR.Vanilla l ^^
-    compile_eq env Type.(Prim Nat32)
+    compile_eq env Type.nat32
   | Nat64Lit _ ->
     BoxedWord64.unbox env Type.Nat64 ^^
     compile_lit_as env (SR.UnboxedWord64 Type.Nat64) l ^^

src/ir_def/arrange_ir.ml

@@ -95,14 +95,15 @@ and prim = function
   | ActorOfIdBlob t   -> "ActorOfIdBlob" $$ [typ t]
   | BlobOfIcUrl       -> Atom "BlobOfIcUrl"
   | IcUrlOfBlob       -> Atom "IcUrlOfBlob"
-  | SelfRef t         -> "SelfRef"    $$ [typ t]
+  | SelfRef t         -> "SelfRef" $$ [typ t]
   | SystemTimePrim    -> Atom "SystemTimePrim"
   | SystemCyclesAddPrim -> Atom "SystemCyclesAddPrim"
   | SystemCyclesAcceptPrim -> Atom "SystemCyclesAcceptPrim"
   | SystemCyclesAvailablePrim -> Atom "SystemCyclesAvailablePrim"
   | SystemCyclesBalancePrim -> Atom "SystemCyclesBalancePrim"
   | SystemCyclesRefundedPrim -> Atom "SystemCyclesRefundedPrim"
   | SystemCyclesBurnPrim -> Atom "SystemCyclesBurnPrim"
+  | SystemTimeoutSetPrim -> Atom "SystemTimeoutSetPrim"
   | SetCertifiedData  -> Atom "SetCertifiedData"
   | GetCertificate    -> Atom "GetCertificate"
   | OtherPrim s       -> Atom s