canister-tools

用于互联网计算机上的canister的Rust库。

功能

• 简单的升级策略。
• canister数据安全功能。
• 用于手动下载和上传堆或稳定内存中的全局变量的canister方法。
• 捕获和序列化堆中canister的全局变量快照，然后下载快照。
• 上传canister全局变量的快照并将其加载到canister的全局变量中。

该库与虚拟内存功能配合使用ic-stable-structures crate。这样，您可以将一些canister数据直接存储在虚拟稳定内存中，同时保持主堆内存中的全局变量在升级后持续存在。

升级策略

thread_local! {
    // canister global data
    static DATA: RefCell<Data> = RefCell::new(Data::default());
}
  
// set a memory-id for the global variable 
const DATA_UPGRADE_MEMORY_ID: MemoryId = MemoryId::new(0);
  
#[init]
fn init() {
    // register the global variable with the memory-id
    canister_tools::init(&DATA, DATA_UPGRADE_MEMORY_ID);
}  
  
#[pre_upgrade]
fn pre_upgrade() {
    // serialize and store the global variables into their memory-ids for the upgrade. 
    canister_tools::pre_upgrade();
}

#[post_upgrade]
fn post_upgrade() {
    // load the data in the memory-id onto the global variable.
    canister_tools::post_upgrade(&DATA, DATA_UPGRADE_MEMORY_ID, None::<fn(OldData) -> Data>);
}

  
  
  

下载canister全局变量的快照，并将快照上传到全局变量。

此库为状态快照管理和稳定内存管理创建了以下canister方法。

type MemoryId = nat8;
type Offset = nat64;
type Length = nat64;
type StateSnapshotLength = nat64;
type WasmPages = nat64;

service : {
    // Takes a snapshot of the data structure registered at the given MemoryId.
    controller_create_state_snapshot : (MemoryId) -> (StateSnapshotLength);
    
    // Download the snapshot of the data corresponding to the given MemoryId.
    // Download the data in chunks.
    controller_download_state_snapshot : (MemoryId, Offset, Length) -> (blob) query;
    
    // Clears the snapshot of the data corresponding to the given MemoryId.
    // When uploading data onto the data structure, call this method first to clear
    // the snapshot before uploading a customized snapshot.
    controller_clear_state_snapshot : (MemoryId) -> ();
    
    // Upload the serialized data structure for the given MemoryId in chunks that can then be deserialized and loaded onto the canister global variable.   
    controller_append_state_snapshot : (MemoryId, blob) -> ();
    
    // Deserializes the snapshot for the data structure corresponding to the given MemoryId
    // and loads it onto the canister's global variable.
    controller_load_state_snapshot : (MemoryId) -> ();

    // Common stable memory functions as canister methods.
    // Useful when using a custom stable-memory strategy for one or some of the MemoryIds. 
    controller_stable_memory_read : (MemoryId, Offset, Length) -> (blob) query;
    controller_stable_memory_write : (MemoryId, Offset, blob) -> ();
    controller_stable_memory_size : (MemoryId) -> (nat64) query;
    controller_stable_memory_grow : (MemoryId, WasmPages) -> (int64);
}