feat: support IC low Wasm memory hook

[luc-blaeser]

Supporting Low Memory Hook in Motoko

The IC allows to implement a low memory hook, which is a warning trigger when main memory is becoming scarce.

For this purpose, a Motoko actor or actor class instance can implement the system function onLowMemory(). This system function is scheduled when canister's free main memory space has fallen below the defined threshold wasm_memory_threshold, that is is part of the canister settings. In Motoko, onLowMemory() implements the canister_on_low_wasm_memory hook defined in the IC specification.

Reference: dfinity/portal#3761

Example of implementing the low memory hook:

actor {
    system func onLowMemory() : async () {
        Debug.print("Low memory!");
    }
}

The following properties should be considered when using the low memory hook:

• The execution of onLowMemory happens with a certain delay, as it is scheduled as a separate asynchronous message that runs after the message in which the threshold was crossed.
• Once executed, onLowMemory will only be triggered again when the main memory free space grows above the threshold (e.g. by lowering the threshold or shrinking the main memory through canister reinstallation) and then again falls below the threshold.
• Traps or unhandled errors in onLowMemory are ignored. They only revert the changes done in onLowMemory.
• Due to its async return type, the onLowMemory function may send further messages and await results.

[github-actions]

Comparing from cef9238 to 0ca1539:
In terms of gas, 5 tests regressed and the mean change is +0.6%.
In terms of size, no changes are observed in 5 tests.

[ggreif]

Just a heads-up, these type definitions will live in type.ml after #4846. I'll take care of this in the migration.

[ggreif]

onLowMemory is kind-of clumsy, what about tightmemory? Would be more in line with the other names...

[luc-blaeser]

Yes, I see. In IC it is called canister_on_low_wasm_memory... Just thought to use a similar name for resemblance, but I am not fully happy either.
Maybe @crusso has some suggestion on how to name this.

[crusso]

I think I prefer onLowMemory to tightmemory. I guess just memory or lowmemory if we want to keep it short and sweet like the others (https://internetcomputer.org/docs/current/motoko/main/reference/language-manual#system-fields), but onLowMemory is more meaningfull.

[ggreif]

What about lowmemory? After all we don't say onGlobalTimerExpiration or onHeartBeat either :-)

[crusso]

Suggested change

	* Once executed, `onLowMemory` is only triggered again when the main memory free space went above the threshold (e.g. by lowering the threshold or shrinking the main memory through canister reinstallation) and when the free space again fell below the threshold.
	* Once executed, `onLowMemory` is only triggered again when the main memory free space exceeds the threshold (e.g. by lowering the threshold or shrinking the main memory through canister reinstallation) and when the free space again falls below the threshold.

Not sure I understand this... should that be an or? Or is the idea that it has to first exceed and then fall below the threshold.

[crusso]

Suggested change

	* Traps or unhandled errors in `onLowMemory` are ignored. They only revert the changes done in `onLowMemory`.
	* Traps or unhandled errors in `onLowMemory` are ignored. Traps only revert the changes done in `onLowMemory`.

I assume errors don't revert.

[crusso]

Oh dear.

[crusso]

I guess we could consider allowing the return type to be async* but the method would need to force the async* somehow. That would avoid another scheduling hop.

Do we want merge this now or wait for the IC implementation to be fixed?