Data.STM.TCursor

This module provides an API very similar to Control.Concurrent.STM.TChan. However, unlike TChan:

• It is based on Data.STM.TList, rather than using an abstract internal representation.
• It separates the read end and write end. This means if the channel has no readers, items written with writeTCursor can be garbage collected.

Here is an implementation of TChan based on TCursor:

type TChan a = (TCursor a, TCursor a)

newTChan = newTCursorPair

newTChanIO = newTCursorPairIO

readTChan = readTCursor . fst

writeTChan = writeTCursor . snd

dupTChan (_, writeEnd) = do
    newReadEnd <- dupTCursor writeEnd
    return (newReadEnd, writeEnd)

unGetTChan = unGetTCursor . fst

isEmptyTChan = isEmptyTCursor . fst

The TCursor type

type TCursor a = TVar (TList a)

A TCursor is a mutable cursor used for traversing items. While uncons and append return the subsequent TList, readTCursor and writeTCursor modify the cursor in-place, and thus behave more like readTChan and writeTChan.

Construction

newTCursorPair :: STM (TCursor a, TCursor a)

O(1). Construct an empty channel, returning the read cursor (fst) and write cursor (snd).

newTCursorPairIO :: IO (TCursor a, TCursor a)

O(1). IO variant of newCursorPair. See newTVarIO for the rationale.

dupTCursor :: TCursor a -> STM (TCursor a)

O(1). Make a copy of a TCursor. Modifying the old cursor with readTCursor or writeTCursor will not affect the new cursor, and vice versa.

Reading and writing

readTCursor :: TCursor a -> STM a

O(1). Read the next item and advance the cursor. retry if the channel is currently empty.

This should be called on the read cursor of the channel.

tryReadTCursor :: TCursor a -> STM (Maybe a)

O(1). Like readTCursor, but return Nothing, rather than retrying, if the list is currently empty.

writeTCursor :: TCursor a -> a -> STM ()

O(1). Append an item and advance the cursor.

This should be called on the write cursor of the channel. See append for more details.

unGetTCursor :: TCursor a -> a -> STM ()

O(1). Put an item back on the channel, where it will be the next item read by readTCursor.

This should be called on the read cursor of the channel.

isEmptyTCursor :: TCursor a -> STM Bool

O(1). Return True if the channel is empty.

This should be called on the read cursor of the channel.