Tracks
/
Factor
Factor
/
Exercises
/
Boatswain's Bilge
Boatswain's Bilge

Boatswain's Bilge

Learning Exercise

Introduction

Pumps, valves, hoses — anything that holds an operating-system resource (an open file, a network connection) has to be released when you're done with it. Factor's destructors vocab wraps these in a framework that guarantees cleanup, even when an error interrupts your code partway through.

The class and the generic

A class joins the framework by extending disposable and implementing the dispose* generic:

USING: accessors destructors kernel ;

TUPLE: pump < disposable opened ;

: <pump> ( -- pump )
    pump new-disposable t >>opened ;

M: pump dispose* f >>opened drop ;

new-disposable ( class -- obj ) allocates the tuple and registers it with the framework — an exception between allocation and the next safe point can't leak the resource. The framework guarantees dispose* runs at most once per object — repeated dispose calls are no-ops.

Public callers use dispose

dispose          ( obj -- )                ! release; safe to call twice
with-disposal    ( disposable quot -- )    ! scope one resource
with-destructors ( quot -- )               ! open a registry scope
&dispose         ( obj -- obj )            ! dispose on normal *or* failure exit
|dispose         ( obj -- obj )            ! dispose only if the scope unwinds

with-disposal is the single-resource form: it pushes the disposable for the inner quotation and releases it on exit.

USING: destructors io ;

<pump> [
    "pumping" print
] with-disposal
! pump released on the way out — even if `print` had thrown

For more than one resource, open a with-destructors scope and register each acquisition. &dispose (ampersand) means "always dispose on the way out, success or failure." |dispose (pipe) means "dispose only on failure" — useful when the success path hands the resource off to a caller who'll take ownership.

[
    <pump> &dispose
    <pump> &dispose
    ! ... use the pumps ...
] with-destructors
! both pumps released

For a bare try/finally without a registry, cleanup (in continuations) is the lower-level primitive — but with-destructors is the idiomatic modern Factor.

Instructions

You're the boatswain on a coastal freighter. The bilge — the lowest compartment of the hull — collects wastewater, and every shift the bilge gear has to be opened, run, and stowed away. Whatever happens mid-pump, the equipment must end up back in its stowed state.

The tests give you <test-pump> to acquire fresh pumps. Each pump has an opened>> slot that reads t while open and f once it's been disposed.

1. Drain the bilge

Define drain-bilge to release a single pump. Calling drain-bilge on the same pump twice should be harmless — the framework handles that for you.

<test-pump> dup drain-bilge opened>> .   ! => f

2. Pump-out routine

Define pump-out to take a pump and a quotation, push the pump onto the stack for the quotation to use, and release the pump after — even if the quotation throws.

<test-pump> [ drop ] pump-out   ! pump released

3. Whole-shift routine

Define shift-routine to take two pumps and a quotation. Open a destructor scope, register both pumps for unconditional release, then call the quotation. Both pumps end up released whether the quotation finishes normally or throws.

The quotation receives both pumps on the stack as inputs.

<test-pump> <test-pump> [ 2drop ] shift-routine
! both pumps released

4. Risky pump-out

Sometimes a pump is on loan — you only want to discard it if something goes wrong, otherwise the next watch needs it left open. Define risky-pump-out to take a pump and a quotation, register the pump for failure-only release, and call the quotation with the pump on the stack.

If the quotation succeeds, the pump stays open. If the quotation throws, the pump is released and the exception propagates.

<test-pump> [ drop ] risky-pump-out                ! stays open
<test-pump> [ drop "boom" throw ] risky-pump-out   ! pump released, throws

5. A custom disposable: the valve

Round out the toolkit with a brand-new disposable — a valve. The tuple is declared for you:

TUPLE: valve < disposable is-open ;
  • Define <valve> ( -- valve ) to construct a fresh valve via new-disposable, with is-open set to t.
  • Implement M: valve dispose* to flip is-open to f.
<valve> is-open>> .                ! => t
<valve> dup dispose is-open>> .    ! => f
Edit via GitHub The link opens in a new window or tab
Factor Exercism

Ready to start Boatswain's Bilge?

Sign up to Exercism to learn and master Factor with 47 concepts163 exercises, and real human mentoring, all for free.