Merge branch 'main' into next

Author: lwshang

.github/workflows/ci.yml

@@ -43,7 +43,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [ubuntu-latest, macos-12]
+        os: [ubuntu-latest, macos-13-large]
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4

Cargo.toml

@@ -31,9 +31,9 @@ opt-level = 'z'
 
 [workspace.dependencies]
 ic0 = { path = "ic0", version = "0.24.0-alpha.1" }
-ic-cdk = { path = "ic-cdk", version = "0.17.0-alpha.1" }
+ic-cdk = { path = "ic-cdk", version = "0.18.0-alpha.1" }
 ic-cdk-management-canister = { path = "ic-cdk-management-canister", version = "0.1.0-alpha.1" }
-ic-cdk-timers = { path = "ic-cdk-timers", version = "0.11.0-alpha.1" }
+ic-cdk-timers = { path = "ic-cdk-timers", version = "0.12.0-alpha.1" }
 
 candid = "0.10.4"
 candid_parser = "0.1.4"

LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2020 DFINITY LLC.
+   Copyright 2020 DFINITY Stiftung.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

ic-cdk-macros/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ic-cdk-macros"
-version = "0.17.0-alpha.1" # sync with ic-cdk
+version = "0.18.0-alpha.1" # sync with ic-cdk
 authors.workspace = true
 edition.workspace = true
 license.workspace = true

ic-cdk-macros/src/export.rs

@@ -33,18 +33,20 @@ enum MethodType {
     Query,
     Heartbeat,
     InspectMessage,
+    OnLowWasmMemory,
 }
 
 impl MethodType {
     pub fn is_lifecycle(&self) -> bool {
-        matches!(
-            self,
+        match self {
             MethodType::Init
-                | MethodType::PreUpgrade
-                | MethodType::PostUpgrade
-                | MethodType::Heartbeat
-                | MethodType::InspectMessage
-        )
+            | MethodType::PreUpgrade
+            | MethodType::PostUpgrade
+            | MethodType::Heartbeat
+            | MethodType::InspectMessage
+            | MethodType::OnLowWasmMemory => true,
+            MethodType::Update | MethodType::Query => false,
+        }
     }
 }
 
@@ -58,6 +60,7 @@ impl std::fmt::Display for MethodType {
             MethodType::Update => f.write_str("update"),
             MethodType::Heartbeat => f.write_str("heartbeat"),
             MethodType::InspectMessage => f.write_str("inspect_message"),
+            MethodType::OnLowWasmMemory => f.write_str("on_low_wasm_memory"),
         }
     }
 }
@@ -312,6 +315,13 @@ pub(crate) fn ic_inspect_message(
     dfn_macro(MethodType::InspectMessage, attr, item)
 }
 
+pub(crate) fn ic_on_low_wasm_memory(
+    attr: TokenStream,
+    item: TokenStream,
+) -> Result<TokenStream, Error> {
+    dfn_macro(MethodType::OnLowWasmMemory, attr, item)
+}
+
 #[cfg(test)]
 mod test {
     use super::*;

ic-cdk-macros/src/lib.rs

@@ -91,3 +91,13 @@ pub fn heartbeat(attr: TokenStream, item: TokenStream) -> TokenStream {
 pub fn inspect_message(attr: TokenStream, item: TokenStream) -> TokenStream {
     handle_debug_and_errors(export::ic_inspect_message, "ic_inspect_message", attr, item)
 }
+
+#[proc_macro_attribute]
+pub fn on_low_wasm_memory(attr: TokenStream, item: TokenStream) -> TokenStream {
+    handle_debug_and_errors(
+        export::ic_on_low_wasm_memory,
+        "ic_on_low_wasm_memory",
+        attr,
+        item,
+    )
+}

ic-cdk-management-canister/src/core/types.rs

@@ -190,10 +190,10 @@ pub enum CanisterInstallMode {
     Reinstall,
     /// Upgrade an existing canister.
     #[serde(rename = "upgrade")]
-    Upgrade(Option<SkipPreUpgrade>),
+    Upgrade(Option<UpgradeFlags>),
 }
 
-/// If set to true, the pre_upgrade step will be skipped during the canister upgrade
+/// Flags for canister installation with [`CanisterInstallMode::Upgrade`].
 #[derive(
     CandidType,
     Serialize,
@@ -208,7 +208,37 @@ pub enum CanisterInstallMode {
     Copy,
     Default,
 )]
-pub struct SkipPreUpgrade(pub Option<bool>);
+pub struct UpgradeFlags {
+    /// If set to `true`, the `pre_upgrade` step will be skipped during the canister upgrade
+    pub skip_pre_upgrade: Option<bool>,
+    /// If set to `Keep`, the WASM heap memory will be preserved instead of cleared.
+    pub wasm_memory_persistence: Option<WasmPersistenceMode>,
+}
+
+/// WASM memory persistence setting for [`UpgradeFlags`].
+#[derive(
+    CandidType,
+    Serialize,
+    Deserialize,
+    Debug,
+    PartialEq,
+    Eq,
+    PartialOrd,
+    Ord,
+    Hash,
+    Clone,
+    Copy,
+    Default,
+)]
+pub enum WasmPersistenceMode {
+    /// Preserve heap memory (only officially supported by Motoko)
+    #[serde(rename = "keep")]
+    Keep,
+    /// Clear heap memory
+    #[serde(rename = "replace")]
+    #[default]
+    Replace,
+}
 
 /// WASM module.
 pub type WasmModule = Vec<u8>;

ic-cdk-timers/CHANGELOG.md

@@ -6,6 +6,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [unreleased]
 
+## [0.11.0] - 2024-11-04
+
+### Changed
+
+- Upgrade `ic-cdk` to v0.17.
+
 ## [0.10.0] - 2024-08-27
 
 ### Changed

ic-cdk-timers/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ic-cdk-timers"
-version = "0.11.0-alpha.1"
+version = "0.12.0-alpha.1"
 authors.workspace = true
 edition.workspace = true
 license.workspace = true

ic-cdk/CHANGELOG.md

@@ -10,12 +10,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Fix update/query macro could not handle function arguments with the same name as the function itself. (#525)
 
+## [0.17.0] - 2024-11-04
+
 ### Changed
 
 - Add `AllowedViewers` variant to `LogVisibility` enum. (#512)
 
 ### Added
 
+- Attribute `#[on_low_wasm_memory]` for low-memory hook. (#528)
 - Support Threshold Schnorr signing management canister API. (#518)
 
 ## [0.16.0] - 2024-08-27

ic-cdk/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ic-cdk"
-version = "0.17.0-alpha.1" # sync with ic-cdk-macros
+version = "0.18.0-alpha.1" # sync with ic-cdk-macros
 authors.workspace = true
 edition.workspace = true
 license.workspace = true
@@ -27,7 +27,7 @@ ic0.workspace = true
 # Dependents won't accidentaly upgrading ic-cdk-macros only but not ic-cdk.
 # ic-cdk-macros is a hidden dependency, re-exported by ic-cdk.
 # It should not be included by users direcly.
-ic-cdk-macros = { path = "../ic-cdk-macros", version = "=0.17.0-alpha.1" }
+ic-cdk-macros = { path = "../ic-cdk-macros", version = "=0.18.0-alpha.1" }
 serde.workspace = true
 serde_bytes.workspace = true
 slotmap = { workspace = true, optional = true }

ic-cdk/README.md

@@ -58,6 +58,7 @@ These macros are directly related to the [Internet Computer Specification](https
 * [`post_upgrade`](https://docs.rs/ic-cdk/latest/ic_cdk/attr.post_upgrade.html)
 * [`inspect_message`](https://docs.rs/ic-cdk/latest/ic_cdk/attr.inspect_message.html)
 * [`heartbeat`](https://docs.rs/ic-cdk/latest/ic_cdk/attr.heartbeat.html)
+* [`on_low_wasm_memory`](https://docs.rs/ic-cdk/latest/ic_cdk/attr.on_low_wasm_memory.html)
 * [`update`](https://docs.rs/ic-cdk/latest/ic_cdk/attr.update.html)
 * [`query`](https://docs.rs/ic-cdk/latest/ic_cdk/attr.query.html)
 

ic-cdk/src/macros.rs

@@ -313,3 +313,24 @@ pub use ic_cdk_macros::heartbeat;
 /// }
 /// ```
 pub use ic_cdk_macros::inspect_message;
+
+/// Register the `canister_on_low_wasm_memory` entry point of a canister.
+///
+/// This attribute macro will export the function `canister_on_low_wasm_memory`
+/// in the canister module.
+///
+/// The function under this attribute must have no return value.
+///
+/// Each canister can only have one `canister_on_low_wasm_memory` entry point.
+///
+/// # Example
+///
+/// ```rust
+/// # use ic_cdk::on_low_wasm_memory;
+/// #[on_low_wasm_memory]
+/// fn low_memory_handler() {
+///     // ...
+/// # unimplemented!()
+/// }
+/// ```
+pub use ic_cdk_macros::on_low_wasm_memory;

ic-cdk/tests/pass/blank_methods.rs

@@ -1,4 +1,6 @@
-use ic_cdk::{heartbeat, init, inspect_message, post_upgrade, pre_upgrade, query, update};
+use ic_cdk::{
+    heartbeat, init, inspect_message, on_low_wasm_memory, post_upgrade, pre_upgrade, query, update,
+};
 
 #[init]
 fn init() {}
@@ -30,4 +32,7 @@ fn heartbeat() {}
 #[inspect_message]
 fn inspect_message() {}
 
+#[on_low_wasm_memory]
+fn on_low_wasm_memory() {}
+
 fn main() {}

library/ic-ledger-types/CHANGELOG.md

@@ -6,6 +6,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [unreleased]
 
+## [0.14.0] - 2024-11-08
+
+### Changed
+
+- Upgrade `ic-cdk` to v0.17.
+
 ### Added
 - as_bytes method to AccountIdentifier in ic-ledger-types
 

library/ic-ledger-types/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ic-ledger-types"
-version = "0.14.0-alpha.1"
+version = "0.15.0-alpha.1"
 authors.workspace = true
 edition.workspace = true
 license.workspace = true