1.13「Motoko——Managing cycles」
Internet computer usage is in ** cycle **
to measure and pay for. The Internet computer maintains the balance of each canister smart contract cycle. Additionally, cycles can be transferred between canisters.
In the Motoko program targeting Internet computers, each actor represents an Internet computer canister and has an associated cycle balance. Ownership of a cycle can be transferred between actors. Cycles are selectively sent and received via messages, i.e. shared function calls. The caller can choose to transfer the cycle through the call, and the callee can choose to accept the cycle provided by the caller. Callers ( Callers ) cannot transfer cycles, and callees ( Callees ) cannot accept cycles unless explicitly instructed to do so .
Callees can accept all, some, or none of the available cycles, up to a limit ( limit ) determined by their actors' current balance . Any remaining cycles will be returned to Callers. If a call traps, all its accompanying cycles are automatically returned to the Callers with no loss.
In the future, we may see Motoko adopt specialized syntax and types to support cycle programming safety. For now, we provide an ad-hoc approach to managing cycles through a low-level imperative API provided by the ExperimentalCycles library in the package repository.
| Note |
| This library is subject to change and will likely be superseded by a higher level of support for later Motoko release cycles. |
ExperimentalCycles库：
The Experimentalcycle library provides command operations for observing an actor's current cycle balance, transferring cycles, and observing refunds.
The library provides the following operations:
func balance() : (amount : Nat)
func available() : (amount : Nat)
func accept(amount : Nat) : (accepted : Nat)
func add(amount : Nat) : ()
func refunded() : (amount : Nat)
The function balance ()returns the actor's current cycle balance. Functions balance ()are stateful and can return different values after calling accept (n), calling a function after cycle, or resuming from await (reflecting a refund).add
Because the cycle measures the computational resources spent, it is common to return different results from one balance()shared function call to the next .balance()
A function available ()that returns the number of cycles currently available ( available ). This amount is the amount received from the current caller, minus the cumulative amount accepted by this call so far. **
When passing through returnor throwexiting from the current shared function or asynchronous expression, all remaining available quantities will be automatically returned to the caller.
The function transfers a certain number of cycles accept()from available()to . balance()It returns the amount actually transferred, which may be lower than requested, for example, if less is available, or if the canister's cycle limit ( limit ) has been reached.
The function add (amount)represents the number of extra cycles to transfer in the next remote call (i.e. the evaluation of a shared function call or an asynchronous expression). At the time of the call, but not before the call, the total incremented() since the last call addwill be balance()subtracted from it. If this total exceeds balance (), the caller trap terminates the call.
The function refunded ()reports the number of cycles that were refunded in the last wait for the current context, or zero if there were no waits. The call refunded ()is for information only and has no effect balance(). Instead, refunds are automatically added to current balances, whether or not they refunded ()are used to observe them.
