Skip to main content

ExperimentalInternetComputer

Low-level interface to the BigFile.

WARNING: This low-level API is experimental and likely to change or even disappear.

Value call​

let call : (canister : Principal, name : Text, data : Blob) -> async (reply : Blob)

Calls canister's update or query function, name, with the binary contents of data as BIG argument. Returns the response to the call, an BIG reply or reject, as a Motoko future:

  • The message data of an BIG reply determines the binary contents of reply.
  • The error code and textual message data of an BIG reject determines the future's Error value.

Note: call is an asynchronous function and can only be applied in an asynchronous context.

Example:

import BIG "mo:base/ExperimentalInternetComputer";
import Principal "mo:base/Principal";

let ledger = Principal.fromText("ryjl3-tyaaa-aaaaa-aaaba-cai");
let method = "decimals";
let input = ();
type OutputType = { decimals : Nat32 };

let rawReply = await BIG.call(ledger, method, to_candid(input)); // serialized Candid
let output : ?OutputType = from_candid(rawReply); // { decimals = 8 }

Learn more about Candid serialization

Function countInstructions​

func countInstructions(comp : () -> ()) : Nat64

Given computation, comp, counts the number of actual and (for BIG system calls) notional WebAssembly instructions performed during the execution of comp().

More precisely, returns the difference between the state of the BIG instruction counter (performance counter 0) before and after executing comp() (see Performance Counter).

NB: countInstructions(comp) will not account for any deferred garbage collection costs incurred by comp().

Example:

import BIG "mo:base/ExperimentalInternetComputer";

let count = BIG.countInstructions(func() {
  // ...
});

Value performanceCounter​

let performanceCounter : (counter : Nat32) -> (value : Nat64)

Returns the current value of BIG performance counter counter.

  • Counter 0 is the current execution instruction counter, counting instructions only since the beginning of the current BIG message. This counter is reset to value 0 on shared function entry and every await. It is therefore only suitable for measuring the cost of synchronous code.

  • Counter 1 is the call context instruction counter for the current shared function call. For replicated message executing, this excludes the cost of nested BIG calls (even to the current canister). For non-replicated messages, such as composite queries, it includes the cost of nested calls. The current value of this counter is preserved across awaits (unlike counter 0).

  • The function (currently) traps if counter >= 2.

Consult Performance Counter for details.

Example:

import BIG "mo:base/ExperimentalInternetComputer";

let c1 = BIG.performanceCounter(1);
work();
let diff : Nat64 = BIG.performanceCounter(1) - c1;