7po3j-syaaa-aaaal-qbqea-cai.icp0.io
Open in
urlscan Pro
2a00:fb01:400:200:5000:45ff:feb5:f777
Public Scan
URL:
https://7po3j-syaaa-aaaal-qbqea-cai.icp0.io/internet-computer-programming-concepts/basic-memory-persistence.html
Submission: On December 01 via api from US — Scanned from CH
Submission: On December 01 via api from US — Scanned from CH
Form analysis 1 forms found in the DOM
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>Text Content
1. The Motoko Programming Language
2.
3. Part 1
4. 1. Introduction
❱
5. 1. 1.1. Getting Started
6. 2. Common Programming Concepts
❱
7. 1. 2.1. Variables
2. 2.2. Mutability
3. 2.3. Comments
4. 2.4. Types
❱
5. 1. 2.4.1. Tuples
2. 2.4.2. Records
3. 2.4.3. Variants
4. 2.4.4. Immutable Arrays
5. 2.4.5. Mutable Arrays
6. 2.5. Operators
❱
7. 1. 2.5.1. Numeric operators
2. 2.5.2. Relational operators
3. 2.5.3. Assignment operators
4. 2.5.4. Text concatenation
5. 2.5.5. Logical expressions
6. 2.5.6. Bitwise operators
7. 2.5.7. Operator precedence
8. 2.6. Pattern Matching
9. 2.7. Functions
10. 2.8. Options and Results
11. 2.9. Control Flow
❱
12. 1. 2.9.1. If Expression
2. 2.9.2. If Else Expression
3. 2.9.3. Switch Expression
13. 2.10. Objects and Classes
❱
14. 1. 2.10.1. Objects
2. 2.10.2. Classes
15. 2.11. Modules and Imports
16. 2.12. Assertions
8. 3. Internet Computer Programming Concepts
❱
9. 1. 3.1. Actors
❱
2. 1. 3.1.1. From Actor to Canister
2. 3.1.2. Canister Calls from Clients
3. 3.2. Principals and Authentication
4. 3.3. Async Data
❱
5. 1. 3.3.1. Shared Types
2. 3.3.2. Candid
6. 3.4. Basic Memory Persistence
❱
7. 1. 3.4.1. Upgrades
2. 3.4.2. Stable Variables
10.
11. Part 2
12. 4. Advanced Types
❱
13. 1. 4.1. Generic Types
2. 4.2. Subtyping
3. 4.3. Recursive Types
4. 4.4. Type Bounds
14. 5. The Base Library
❱
15. 1. 5.1. Primitive Types
❱
2. 1. 5.1.1. Bool
2. 5.1.2. Nat
3. 5.1.3. Int
4. 5.1.4. Float
5. 5.1.5. Principal
6. 5.1.6. Text
7. 5.1.7. Char
8. 5.1.8. Bounded Number Types
❱
9. 1. 5.1.8.1. Nat8
2. 5.1.8.2. Nat16
3. 5.1.8.3. Nat32
4. 5.1.8.4. Nat64
5. 5.1.8.5. Int8
6. 5.1.8.6. Int16
7. 5.1.8.7. Int32
8. 5.1.8.8. Int64
10. 5.1.9. Blob
3. 5.2. Utility Modules
❱
4. 1. 5.2.1. Iterators
2. 5.2.2. Hash
3. 5.2.3. Option
4. 5.2.4. Result
5. 5.2.5. Order
6. 5.2.6. Error
7. 5.2.7. Debug
5. 5.3. Data Structures
❱
6. 1. 5.3.1. Array
2. 5.3.2. List
3. 5.3.3. Buffer
4. 5.3.4. HashMap
5. 5.3.5. RBTree
7. 5.4. More Data Structures
8. 5.5. IC APIs
❱
9. 1. 5.5.1. Time
2. 5.5.2. Timer
3. 5.5.3. CertifiedData
4. 5.5.4. Random
5. 5.5.5. Experimental
16. 6. Advanced Concepts
❱
17. 1. 6.1. Async Programming
2. 6.2. Scalability
❱
3. 1. 6.2.1. Actor Classes
2. 6.2.2. Stable Storage
4. 6.3. System API's
❱
5. 1. 6.3.1. Message Inspection
2. 6.3.2. Timers
3. 6.3.3. Certified Variables
4. 6.3.4. Pre-upgrade and Post-upgrade
5. 6.3.5. Cryptographic Randomness
18.
19. Part 3
20. 7. Project Deployment
❱
21. 1. 7.1. Installing the SDK
2. 7.2. Local Deployment
3. 7.3. Canister Status
4. 7.4. Identities and PEM Files
5. 7.5. Cycles and ICP
6. 7.6. Cycles Wallet
7. 7.7. IC Deployment
22. 8. Common Internet Computer Canisters
❱
23. 1. 8.1. IC Management Canister
2. 8.2. ICP Ledger Canister
3. 8.3. Cycle Minting Canister
24. 9. Internet Computer Standards
❱
25. 1. 9.1. ICRC1
26. 10. Tokenized Comments Example
27.
28. APPENDIX
29. 11. TABLES
* Light
* Rust
* Coal
* Navy
* Ayu
THE MOTOKO PROGRAMMING LANGUAGE BOOK
BASIC MEMORY PERSISTENCE
Every actor exposes a public interface. A deployed actor is sometimes referred
to as a service. We interact with a service by calling the public shared
functions of the underlying actor.
The state of the actor can not change during a query function call. When we call
a query function, we could pass in some data as arguments. This data could be
used for a computation, but no data could be stored in the actor during the
query call.
The state of the actor may change during an update or oneway function call. Data
provided as arguments (or data generated without arguments in the function
itself) could be stored inside the actor.
CANISTER MAIN MEMORY
Every actor running in a canister has access to a 4GB main 'working' memory (in
Feb 2023). This is like the RAM memory.
Code in actors directly acts on main memory:
* The values of (top-level) mutable and immutable variables are stored in main
memory.
* Public and private functions in actors, that read and write data, do so from
and to main memory.
* Imported classes from modules are instantiated as objects in main memory.
* Imported functions from modules operate on main memory.
The same applies for any other imported item that is used inside an actor.
MEMORY PERSISTENCE ACROSS FUNCTION CALLS
Consider the actor from our previous example with only the mutable variable
latestComment and the functions readComment and writeComment:
actor {
private var latestComment = "";
public shared query func readComment() : async Text {
latestComment;
};
public shared func writeComment(comment : Text) : async () {
latestComment := comment;
};
};
The mutable variable latestComment is stored in main memory. Calling the update
function writeComment mutates the state of the mutable variable latestComment in
main memory.
For instance, we could call writeComment with an argument "Motoko is great!".
The variable latestComment will be set to that value in main memory. The mutable
variable now has a new state. Another call to readComment would return the new
value.
SERVICE UPGRADES AND MAIN MEMORY
Now, suppose we would like to extend the functionality of our service by adding
another public shared function (like the deleteComment function). We would need
to write the function in Motoko, edit our original Motoko source file and go
through the deployment process again.
The redeployment of our actor will wipe out the main memory of the actor!
There are two main ways to upgrade the functionality of a service without
resetting the memory state of the underlying actor.
This chapter describes stable variables which are a way to persist the state of
mutable variables across upgrades. Another way is to use stable memory, which
will be discussed later in this book.