16.2 Plumbers🔗ℹ

A plumber supports flush callbacks, which are normally triggered just before a Rhombus process exits. For example, a flush callback might flush an output port’s buffer.Flush callbacks are roughly analogous to the standard C library’s atexit, but flush callback can also be used in other, similar scenarios.

There is no guarantee that a flush callback will be called before a process terminates—either because the plumber is not the original plumber that is flushed on exit, or because the process is terminated forcibly (e.g., through a custodian shutdown).

The Plumber.FlushHandle class represents a flush handle, which records a particular registration of a flush callback.

The flush callbacks to call are collected from plumber before the first one is called. If a flush callback registers a new flush callback, the new one is not called. If a flush callback raises an exception or otherwise escapes, then the remaining flush callbacks are not called.

The result flush handle represents the registration of the callback, and it can be used with Plumber.FlushHandle.remove to unregister the callback.

The given flush is reachable from the flush handle, but if weak is true, then plumber retains only a weak reference to the result flush handle (and thus flush).

When flush is called as a flush callback, it is passed the same value that is returned by Plumber.add_flush so that flush can conveniently unregister itself. The call of flush is within a continuation barrier.

If the registration represented by fh has been removed already, then Plumber.FlushHandle.remove has no effect.