14.11 Plumbers

► |  | The Racket Reference

1 | Language Model
2 | Notation for Documentation
3 | Syntactic Forms
4 | Datatypes
5 | Structures
6 | Classes and Objects
7 | Units
8 | Contracts
9 | Pattern Matching
10 | Control Flow
11 | Concurrency and Parallelism
12 | Macros
13 | Input and Output
14 | Reflection and Security
15 | Operating System
16 | Memory Management
17 | Unsafe Operations
18 | Running Racket
| Bibliography
| Index

▼ | 14 | Reflection and Security

14.1 | Namespaces
14.2 | Evaluation and Compilation
14.3 | The racket/ load Language
14.4 | Module Names and Loading
14.5 | Impersonators and Chaperones
14.6 | Security Guards
14.7 | Custodians
14.8 | Thread Groups
14.9 | Structure Inspectors
14.10 | Code Inspectors
14.11 | Plumbers
14.12 | Sandboxed Evaluation
14.13 | The racket/ repl Library
14.14 | Linklets and the Core Compiler

On this page:

plumber?
make-plumber
current-plumber
plumber-flush-all
plumber-flush-handle?
plumber-add-flush!
plumber-flush-handle-remove!

top ← prev up next →

#### 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).

> procedure (plumber? v) → boolean?
> v : any/c

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

Added in version 6.0.1.8 of package base.

> procedure (make-plumber) → plumber?

Creates a new plumber.

Plumbers have no hierarchy (unlike custodians or inspectors), 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.

> parameter (current-plumber) → plumber?
> (current-plumber plumber) → void?
> plumber : plumber?

A parameter that determines a current plumber for flush 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.

> procedure (plumber-flush-all plumber) → void?
> plumber : plumber?

Calls all flush callbacks that are registered with plumber.

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.

Added in version 6.0.1.8 of package base.

> procedure (plumber-flush-handle? v) → boolean?
> v : any/c

Returns #t if v is a flush handle represents the registration of a flush callback, #f otherwise.

Added in version 6.0.1.8 of package base.

> procedure (plumber-add-flush! plumber proc [weak?]) → plumber-flush-handle?
> plumber : plumber?
> proc : (plumber-flush-handle? . -> . any)
> weak? : any/c = #f

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 a weak 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 of proc is within a continuation barrier.

Added in version 6.0.1.8 of package base.

> procedure (plumber-flush-handle-remove! handle) → void?
> handle : plumber-flush-handle?

Unregisters the flush callback that was registered by the plumber-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.

top ← prev up next →