diff --git a/src/ExperimentalInternetComputer.mo b/src/ExperimentalInternetComputer.mo index af441e07..bf59644e 100644 --- a/src/ExperimentalInternetComputer.mo +++ b/src/ExperimentalInternetComputer.mo @@ -55,6 +55,31 @@ module { // performance_counter costs around 200 extra instructions, we perform an empty measurement to decide the overhead let overhead = pre - init; post - pre - overhead - } + }; + + /// Returns the current value of IC _performance counter_ `counter`. + /// + /// * Counter `0` is the _current execution instruction counter_, counting instructions only since the beginning of the current IC 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 IC 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](https://internetcomputer.org/docs/current/references/ic-interface-spec#system-api-performance-counter) for details. + /// + /// Example: + /// ```motoko no-repl + /// import IC "mo:base/ExperimentalInternetComputer"; + /// + /// let c1 = IC.performanceCounter(1); + /// work(); + /// let diff : Nat64 = IC.performanceCounter(1) - c1; + /// ``` + public let performanceCounter : (counter : Nat32) -> (value: Nat64) = Prim.performanceCounter; }