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 lowmemory(). 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, lowmemory() 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 lowmemory() : async* () {
        Debug.print("Low memory!");
    }
}

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

• The execution of lowmemory 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, lowmemory 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 lowmemory are ignored. They only revert the changes done in lowmemory.
• Due to its async* return type, the lowmemory function may send further messages and await results.

[github-actions]

Comparing from 607ecfd to e349c26:
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.

[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?

[luc-blaeser]

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?

I changed it to async*. Thanks for the suggestion.

I think we can merge it as soon as it is ready from our side. The IC fix can come later and would be automatically become effective.

[ggreif]

Added one suggestion, otherwise LGTM!

[luc-blaeser]

Thanks for reviewing!