A Frame is a higher-order type built on top of Pipe. It enables a richer composition with the ability to finalize resources in a manner that is:

• Prompt: You can close resources when you no longer need input from them
• Deterministic: Composition finalizes every Frame when one terminates

Frames differ from Pipes in that they do not form monads, but instead form parametrized monads. Unfortunately, parametrized monads are not mainstream in Haskell and require a ton of extensions along with a modified Prelude in order to recover do notation, so this first release of the Frame implementation essentially "in-lines" the parametrized monad by splitting it into two monads. Future releases will split off a version that takes advantage of parametrized monads for a much simpler underlying type and a significantly cleaner implementation.

Ordinary users should start at the section "Create Frames", but if you encounter weird type errors and want to understand them, then consult the "Types" section.

The first step to convert Pipe code to Frame code is to replace all yields with yieldFs and all awaits with awaitFs.

contrived = do   -->  contrived = do
    x1 <- await  -->      x1 <- awaitF
    yield x1     -->      yieldF x1
    x2 <- await  -->      x2 <- awaitF
    yield x2     -->      yieldF x2

The second step to convert Pipe code to Frame code is to mark the point where your Pipe no longer awaits by wrapping it in the close function and then wrapping the Pipe in a Frame newtype:

contrived :: (Monad m) => Frame a a m ()
contrived = Frame $ do
    x1 <- awaitF
    yieldF x1
    x2 <- awaitF
    close $ yieldF x2

If a non-terminating pipe demands input indefinitely, there is no need to close it. It will type-check if the return value is polymorphic as a result of non-termination.

The third (optional) step to convert Pipe code to Frame code is to use catchP or finallyP to register finalizers for blocks of code.

contrived :: Frame a a IO ()
contrived = Frame $ do
    catchP (putStrLn "Stage 1 interrupted") $ do
        x1 <- awaitF
        catchP (putStrLn "Stage 1(b) interrupted") $ yieldF x1
    catchP (putStrLn "Stage 2 interrupted") $ do
        x2 <- awaitF
        close $ yieldF x2

The fourth step to convert Pipe code to Frame code is to use (<-<) to compose Frames instead of (<+<).

printer  :: Frame a Void IO r
fromList :: (Monad m) => [a] -> Frame () a m ()

p :: Stack IO ()
p = printer <-< contrived <-< fromList [1..]

Similarly, idF replaces idP.

When a Frame terminates, the FrameC category strictly orders the finalizers from upstream to downstream. Specifically:

• When any Frame closes its input end, it finalizes all Frames upstream of it. These finalizers are ordered from upstream to downstream.
• A Frame is responsible for finalizing its own resources under ordinary operation (either manually, or using finallyP).
• When a Frame terminates, everything downstream of it is finalized. These finalizers are ordered from upstream to downstream.

The Category instance for FrameC provides the same strong guarantees as the Lazy category. This confers many practical advantages:

• Finalizers are never duplicated or dropped in corner cases.
• The grouping of composition will never affect the ordering or behavior of finalizers.
• Finalization does not grow more complex the more Frames you add in your Stack.
• You can reason about the finalization behavior of each Frame independently of other Frames it is composed with.

The final step to convert Pipe code to Frame code is to replace runPipe with runFrame.

printer  :: Frame a Void IO r
take     :: (Monad m) => Int -> Frame a a m ()
fromList :: (Monad m) => [a] -> Frame () a m ()

>>> runFrame $ printer <-< contrived <-< fromList [1..]
1
2

>>> runFrame $ printer <-< contrived <-< fromList [1]
1
Stage 2 interrupted

>>> runFrame $ printer <-< take 1 <-< contrived <-< fromList [1..]
Stage 1(b) interrupted
Stage 1 interrupted
1

For the last example, remember that take is written to close its input end before yielding its final value, which is why the finalizers run before printer receives the 1.