From 4f109b2c73c7e3df6c5168d5dae60e16c60e0e1b Mon Sep 17 00:00:00 2001 From: Islam El-Ashi Date: Fri, 22 Mar 2024 15:22:23 +0100 Subject: [PATCH 1/6] feat: on low wasm memory hook --- spec/_attachments/ic.did | 2 ++ spec/index.md | 20 +++++++++++++++++++- 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/spec/_attachments/ic.did b/spec/_attachments/ic.did index a34f3318..37032bf4 100644 --- a/spec/_attachments/ic.did +++ b/spec/_attachments/ic.did @@ -7,6 +7,7 @@ type canister_settings = record { memory_allocation : opt nat; freezing_threshold : opt nat; reserved_cycles_limit : opt nat; + low_wasm_memory_threshold : opt nat; }; type definite_canister_settings = record { @@ -15,6 +16,7 @@ type definite_canister_settings = record { memory_allocation : nat; freezing_threshold : nat; reserved_cycles_limit : nat; + low_wasm_memory_threshold: nat; }; type change_origin = variant { diff --git a/spec/index.md b/spec/index.md index 61a750b0..b180df46 100644 --- a/spec/index.md +++ b/spec/index.md @@ -1163,6 +1163,8 @@ In order for a WebAssembly module to be usable as the code for the canister, it - If it exports a function called `canister_heartbeat`, the function must have type `() -> ()`. +- If it exports a function called `canister_on_low_wasm_memory`, the function must have type `() -> ()`. + - If it exports a function called `canister_global_timer`, the function must have type `() -> ()`. - If it exports any functions called `canister_update `, `canister_query `, or `canister_composite_query ` for some `name`, the functions must have type `() -> ()`. @@ -1215,6 +1217,8 @@ The canister provides entry points which are invoked by the IC under various cir - The canister may export functions with name `canister_composite_query ` and type `() -> ()`. +- The canister may export functions with name `canister_on_low_wasm_memory` and type `() -> ()`. + - The canister table may contain functions of type `(env : i32) -> ()` which may be used as callbacks for inter-canister calls and composite query methods. If the execution of any of these entry points traps for any reason, then all changes to the WebAssembly state, as well as the effect of any externally visible system call (like `ic0.msg_reply`, `ic0.msg_reject`, `ic0.call_perform`), are discarded. For upgrades, this transactional behavior applies to the `canister_pre_upgrade`/`canister_post_upgrade` sequence as a whole. @@ -1289,6 +1293,18 @@ While an implementation will likely try to keep the interval between the value o ::: +#### On Low Wasm Memory {#on-low-wasm-memory} + +A canister can export a function with the name `canister_on_low_wasm_memory`, which is scheduled whenever the canister's wasm memory size in bytes grows from below a threshold `t` to >= t. +The threshold `t` can be defined in the [canister's settings](#ic-canister_status) and by default it is set to 264 − 1. + +:::note + +While the above function is scheduled immediately once the condition above is triggered, it may not necessarily be executed immediately if it does not have enough cycles. +If the canister gets frozen immediately after the function is scheduled for execution, the function will run once the canister's unfrozen _if_ the canister's wasm memory remains above the threshold `t`. + +::: + #### Callbacks Callbacks are addressed by their table index (as a proxy for a Wasm `funcref`). @@ -1399,7 +1415,7 @@ The comment after each function lists from where these functions may be invoked: - `F`: from `canister_inspect_message` -- `T`: from *system task* (`canister_heartbeat` or `canister_global_timer`) +- `T`: from *system task* (`canister_heartbeat` or `canister_global_timer` `canister_on_low_wasm_memory`) - `*` = `I G U Q CQ Ry Rt CRy CRt C CC F T` (NB: Not `(start)`) @@ -2077,6 +2093,8 @@ Indicates various information about the canister. It contains: - The reserved cycles limit of the canister, i.e., the maximum number of cycles that can be in the canister's reserved balance after increasing the canister's memory allocation and/or actual memory usage. + - The "low wasm memory" threshold, which is used to determine when the `on_low_wasm_memory` function is executed. See {#on-low-wasm-memory}. + - A SHA256 hash of the module installed on the canister. This is `null` if the canister is empty. - The actual memory usage of the canister. From 5c4c3d94ea5be57b33e11c644211afae6802fa84 Mon Sep 17 00:00:00 2001 From: Islam El-Ashi Date: Fri, 22 Mar 2024 15:30:55 +0100 Subject: [PATCH 2/6] . --- spec/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/index.md b/spec/index.md index b180df46..cbd29850 100644 --- a/spec/index.md +++ b/spec/index.md @@ -1295,7 +1295,7 @@ While an implementation will likely try to keep the interval between the value o #### On Low Wasm Memory {#on-low-wasm-memory} -A canister can export a function with the name `canister_on_low_wasm_memory`, which is scheduled whenever the canister's wasm memory size in bytes grows from below a threshold `t` to >= t. +A canister can export a function with the name `canister_on_low_wasm_memory`, which is scheduled whenever the canister's wasm memory size in bytes grows from below a threshold `t` to >= `t`. The threshold `t` can be defined in the [canister's settings](#ic-canister_status) and by default it is set to 264 − 1. :::note @@ -2093,7 +2093,7 @@ Indicates various information about the canister. It contains: - The reserved cycles limit of the canister, i.e., the maximum number of cycles that can be in the canister's reserved balance after increasing the canister's memory allocation and/or actual memory usage. - - The "low wasm memory" threshold, which is used to determine when the `on_low_wasm_memory` function is executed. See {#on-low-wasm-memory}. + - The "low wasm memory" threshold, which is used to determine when the [canister_on_low_wasm_memory](#on-low-wasm-memory) function is executed. - A SHA256 hash of the module installed on the canister. This is `null` if the canister is empty. From 071a811f98d1bc77ec0f01a2d70c6eaead65f8c1 Mon Sep 17 00:00:00 2001 From: mraszyk <31483726+mraszyk@users.noreply.github.com> Date: Fri, 21 Jun 2024 11:00:41 +0200 Subject: [PATCH 3/6] Update spec/index.md Co-authored-by: Dragoljub Djuric --- spec/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/index.md b/spec/index.md index cbd29850..997ee621 100644 --- a/spec/index.md +++ b/spec/index.md @@ -1415,7 +1415,7 @@ The comment after each function lists from where these functions may be invoked: - `F`: from `canister_inspect_message` -- `T`: from *system task* (`canister_heartbeat` or `canister_global_timer` `canister_on_low_wasm_memory`) +- `T`: from *system task* (`canister_heartbeat` or `canister_global_timer` or `canister_on_low_wasm_memory`) - `*` = `I G U Q CQ Ry Rt CRy CRt C CC F T` (NB: Not `(start)`) From 5a08b3457b70a3d365e306f5839472c5fc625fcd Mon Sep 17 00:00:00 2001 From: Dragoljub Djuric Date: Mon, 22 Jul 2024 14:44:24 +0200 Subject: [PATCH 4/6] Update spec/index.md --- spec/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/index.md b/spec/index.md index a87666b0..315552a1 100644 --- a/spec/index.md +++ b/spec/index.md @@ -1354,7 +1354,7 @@ While an implementation will likely try to keep the interval between the value o #### On Low Wasm Memory {#on-low-wasm-memory} -A canister can export a function with the name `canister_on_low_wasm_memory`, which is scheduled whenever the canister's wasm memory size in bytes grows from below a threshold `t` to >= `t`. +A canister can export a function with the name `canister_on_low_wasm_memory`, which is scheduled whenever the canister's remaining wasm memory size in bytes falls from above a threshold `t` to < `t`. The threshold `t` can be defined in the [canister's settings](#ic-canister_status) and by default it is set to 264 − 1. :::note From f4128a1d483a2f7563df2c708be3742f8f639cb1 Mon Sep 17 00:00:00 2001 From: Dragoljub Djuric Date: Mon, 22 Jul 2024 14:44:37 +0200 Subject: [PATCH 5/6] Update spec/index.md --- spec/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/index.md b/spec/index.md index 315552a1..715a51ad 100644 --- a/spec/index.md +++ b/spec/index.md @@ -1355,7 +1355,7 @@ While an implementation will likely try to keep the interval between the value o #### On Low Wasm Memory {#on-low-wasm-memory} A canister can export a function with the name `canister_on_low_wasm_memory`, which is scheduled whenever the canister's remaining wasm memory size in bytes falls from above a threshold `t` to < `t`. -The threshold `t` can be defined in the [canister's settings](#ic-canister_status) and by default it is set to 264 − 1. +The threshold `t` can be defined in the [canister's settings](#ic-canister_status) and by default it is set to 0. :::note From e4d9c8261f9e65d7ea27a415250e89705a710544 Mon Sep 17 00:00:00 2001 From: Dragoljub Djuric Date: Tue, 23 Jul 2024 08:05:02 +0000 Subject: [PATCH 6/6] Change name of the field. --- spec/_attachments/ic.did | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/_attachments/ic.did b/spec/_attachments/ic.did index 624c99d7..a1ddfe46 100644 --- a/spec/_attachments/ic.did +++ b/spec/_attachments/ic.did @@ -14,7 +14,7 @@ type canister_settings = record { reserved_cycles_limit : opt nat; log_visibility : opt log_visibility; wasm_memory_limit : opt nat; - low_wasm_memory_threshold : opt nat; + wasm_memory_threshold : opt nat; }; type definite_canister_settings = record { @@ -25,7 +25,7 @@ type definite_canister_settings = record { reserved_cycles_limit : nat; log_visibility : log_visibility; wasm_memory_limit : nat; - low_wasm_memory_threshold: nat; + wasm_memory_threshold: nat; }; type change_origin = variant {