feat: define ExperimentalInternetComputer.performanceCounter : Nat32 …

…-> Nat64; (#600)

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
call context.
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;
```

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;
 
 }