14.11 Plumbers (original) (raw)

14.11 Plumbers🔗ℹ

A plumber supports flush callbacks, which are normally triggered just before a Racket process or place 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 by the default exit handler, or because the process is terminated forcibly (e.g., through a custodian shutdown).

Returns #t if v is a plumber value,#f otherwise.

Added in version 6.0.1.8 of package base.

Creates a new plumber.

Plumbers have no hierarchy (unlike custodians orinspectors), but a flush callback can be registered in one plumber to call plumber-flush-all with another plumber.

Added in version 6.0.1.8 of package base.

A parameter that determines a current plumber forflush callbacks. For example, creating an output file stream port registers a flush callback with the current plumber to flush the port as long as the port is opened.

Added in version 6.0.1.8 of package base.

Calls all flush callbacks that are registered with plumber.

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

Added in version 6.0.1.8 of package base.

Returns #t if v is a flush handlerepresents the registration of a flush callback, #fotherwise.

Added in version 6.0.1.8 of package base.

Registers proc as a flush callback with plumber, so that proc is called when plumber-flush-all is applied to plumber.

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

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

When proc is called as a flush callback, it is passed the same value that is returned by plumber-add-flush! so that proc can conveniently unregister itself. The call ofproc is within a continuation barrier.

Added in version 6.0.1.8 of package base.

Unregisters the flush callback that was registered by theplumber-add-flush! call that produced handle.

If the registration represented by handle has been removed already, then plumber-flush-handle-remove! has no effect.

Added in version 6.0.1.8 of package base.