Internet Computer の使用量は測定されており, サイクル で支払われます. Internet Computer はキャニスタ・スマート・コントラクト毎にサイクルの収支を管理します. さらにサイクルはキャニスタ・スマート・コントラクト間で振り替えることができます.
Usage of the Internet Computer is measured, and paid for, in cycles. The Internet Computer maintains a balance of cycles per canister smart contract. In addition, cycles can be transferred between canister smart contracts.
Motoko プログラムは Internet Computer をターゲットとしているので, 各アクタは Internet Computer のキャニスタ・スマート・コントラクトを現しており, サイクル収支に紐付いています. サイクルの所有権はアクタ間で移転できます. サイクルはメッセージを経由して, すなわち共有関数呼び出しで, 選択的に送受信されます. 呼び出し元は呼び出し時にサイクルの転送を選択でき, 呼び出し先は呼び出し元が用意したサイクルを受け取るかどうかを選択できます. 明示的に指定しない限り, 呼び出し元からサイクルを転送し, 呼び出し先がそれを受け取ることはありません.
In Motoko programs targeting the Internet Computer, each actor represents an Internet Computer canister smart contract, and has an associated balance of cycles. The ownership of cycles can be transferred between actors. Cycles are selectively sent and received through messages, that is, shared function calls. A caller can choose to transfer cycles with a call, and a callee can choose to accept cycles that are made available by the caller. Unless explicitly instructed, no cycles are transferred by callers or accepted by callees.
呼び出し先は用意されたサイクルのうち, アクタの現在の収支によって決められる限度内で, すべてを受け取る, 一部を受け取る, あるいはまったく受け取らないということができます. もし呼び出しがトラップしたら, それに付随するすべてのサイクルは自動的に呼び出し元に払い戻され, 損失はありません.
Callees can accept all, some or none of the available cycles up to limit determined by their actor’s current balance. Any remaining cycles are refunded to the caller. If a call traps, all its accompanying cycles are automatically refunded to the caller, without loss.
将来的には, サイクルをより安全にプログラミングできるように Motoko 専用の構文と型を採用するかもしれません. 今のところは, 一時的ではありますが, サイクルを base パッケージの ExperimentalCycles ライブラリが提供する低レベルで手続き的な API を通じて管理します.
In future, we may see Motoko adopt dedicated syntax and types to support safer programming with cycles. For now, we provide a temporary way to manage cycles through a low-level imperative API provided by the ExperimentalCycles library in package base.
:::note
このライブラリは変わることがあり, Motoko の将来のヴァージョンではより高いレベルのサイクルのサポートで置き換えられる可能性があります.
This library is subject to change and likely to be replaced by more high-level support for cycles in later versions of Motoko.
:::
ExperimentalCycles LibraryExperimentalCycles ライブラリは, あるアクタのサイクルの現在の収支を監視したり, サイクルを振り替えたり, 払い戻しを監視したりする手続き的な操作を提供しています.
The ExperimentalCycles library provides imperative operations for observing an actor’s current balance of cycles, 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)
banace() 関数はそのアクタの現在の収支を amount として返します. balance() 関数は状態を持ち, accept(n) を呼び出した後, サイクルを 追加 して何かの関数を呼び出したとき, await から戻ったとき (払い戻しが反映される) には異なる値を返すでしょう.
Function balance() returns the actor’s current balance of cycles as amount. Function balance() is stateful and may return different values after calls to accept(n), calling a function after adding cycles, or resuming from await (reflecting a refund).
:::danger
サイクルは消費された計算資源を測るものなので, 共有関数のある呼び出しから次の呼び出しの間にbalance() の値は減少するのが一般的です.
Since cycles measure computational resources spent, the value of balance() generally decreases from one shared function call to the next.
:::
available() 関数はサイクルの現在残っている amount (量) を返します. これは現在の呼び出し元から受け取った量からこの呼び出しによってこれまでに accept された (受け取られた) 量の積算量を引いたものです. この共有関数や 非同期 式から return か throw によって抜けるときに残っている量は自動的に呼び出し元に払い戻されます.
Function available(), returns the currently available amount of cycles. This is the amount received from the current caller, minus the cumulative amount accepted so far by this call. On exit from the current shared function or async expression via return or throw any remaining available amount is automatically refunded to the caller.
accept 関数は, amount を available() から balance() に移します. 実際に移された量を返しますが, これは例えば用意できた量が足りなかったとか, キャニスタ・スマート・コントラクトの収支上限に達したとかの場合には要求した量より少なくなります.
Function accept transfers amount from available() to balance(). It returns the amount actually transferred, which may be less than requested, for example, if less is available, or if canister smart contract balance limits are reached.
add(amont) 関数は, 次の遠隔呼び出し, つまり共有関す呼び出しやasync 式の評価で転送されるサイクルの追加量を示します. (事前にではなく) 呼び出し時に, 最後の呼び出し以降に add された総量が, balance() から差し引かれます.
Function add(amount) indicates the additional amount of cycles to be transferred in the next remote call, i.e. evaluation of a shared function call or async expression. Upon the call, but not before, the total amount of units added since the last call is deducted from balance(). If this total exceeds balance(), the caller traps, aborting the call.
:::note
追加された量 (add 毎に増えていく) の暗黙の登録が, 共有関数に入るとき, 各共有関数の呼び出しや await からの回復毎にゼロにリセットされます.
the implicit register of added amounts, incremented on each add, is reset to zero on entry to a shared function, and after each shared function call or on resume from an await.