Control.Concurrent.Chan.Unagi.Unboxed

unagi-chan-0.4.1.4: Fast concurrent queues with a Chan-like API, and more

Safe Haskell | None
Language | Haskell2010

Control.Concurrent.Chan.Unagi.Unboxed

Contents

- Creating channels
- Channel operations
  - Reading
  - Writing
  - Broadcasting

Synopsis

- newChan :: UnagiPrim a => IO (InChan a, OutChan a)
- data InChan a
- data OutChan a
- class (Prim a, Eq a) => UnagiPrim a where
  - atomicUnicorn :: Maybe a
- readChan :: UnagiPrim a => OutChan a -> IO a
- readChanOnException :: UnagiPrim a => OutChan a -> (IO a -> IO ()) -> IO a
- tryReadChan :: UnagiPrim a => OutChan a -> IO (Element a, IO a)
- newtype Element a = Element {
  - tryRead :: IO (Maybe a)
  }
- getChanContents :: UnagiPrim a => OutChan a -> IO [a]
- writeChan :: UnagiPrim a => InChan a -> a -> IO ()
- writeList2Chan :: UnagiPrim a => InChan a -> [a] -> IO ()
- dupChan :: InChan a -> IO (OutChan a)

# Creating channels

newChan :: UnagiPrim a => IO (InChan a, OutChan a) #

Create a new channel, returning its write and read ends.

data InChan a #

The write end of a channel created with `newChan`.

#### Instances

Instances details

Eq (InChan a) # |
Instance details Defined in Control.Concurrent.Chan.Unagi.Unboxed.Internal Methods (==) :: InChan a -> InChan a -> Bool # (/=) :: InChan a -> InChan a -> Bool #

data OutChan a #

The read end of a channel created with `newChan`.

#### Instances

Instances details

Eq (OutChan a) # |
Instance details Defined in Control.Concurrent.Chan.Unagi.Unboxed.Internal Methods (==) :: OutChan a -> OutChan a -> Bool # (/=) :: OutChan a -> OutChan a -> Bool #

class (Prim a, Eq a) => UnagiPrim a where #

Our class of types supporting primitive array operations. Instance method definitions are architecture-dependent.

Minimal complete definition

Nothing

Methods

atomicUnicorn :: Maybe a #

When the read and write operations of the underlying `Prim` instances on aligned memory are atomic, this may be set to `Just x` where `x` is some rare (i.e. unlikely to occur frequently in your data) magic value; this might help speed up some `UnagiPrim` operations.

Where those `Prim` instance operations are not atomic, this *must* be set to `Nothing`.

#### Instances

Instances details

UnagiPrim Int16 # |
Instance details Defined in Control.Concurrent.Chan.Unagi.Unboxed.Internal Methods atomicUnicorn :: Maybe Int16 #
UnagiPrim Int32 # |
Instance details Defined in Control.Concurrent.Chan.Unagi.Unboxed.Internal Methods atomicUnicorn :: Maybe Int32 #
UnagiPrim Int64 # |
Instance details Defined in Control.Concurrent.Chan.Unagi.Unboxed.Internal Methods atomicUnicorn :: Maybe Int64 #
UnagiPrim Int8 # |
Instance details Defined in Control.Concurrent.Chan.Unagi.Unboxed.Internal Methods atomicUnicorn :: Maybe Int8 #
UnagiPrim Word16 # |
Instance details Defined in Control.Concurrent.Chan.Unagi.Unboxed.Internal Methods atomicUnicorn :: Maybe Word16 #
UnagiPrim Word32 # |
Instance details Defined in Control.Concurrent.Chan.Unagi.Unboxed.Internal Methods atomicUnicorn :: Maybe Word32 #
UnagiPrim Word64 # |
Instance details Defined in Control.Concurrent.Chan.Unagi.Unboxed.Internal Methods atomicUnicorn :: Maybe Word64 #
UnagiPrim Word8 # |
Instance details Defined in Control.Concurrent.Chan.Unagi.Unboxed.Internal Methods atomicUnicorn :: Maybe Word8 #
UnagiPrim Char # |
Instance details Defined in Control.Concurrent.Chan.Unagi.Unboxed.Internal Methods atomicUnicorn :: Maybe Char #
UnagiPrim Double # |
Instance details Defined in Control.Concurrent.Chan.Unagi.Unboxed.Internal Methods atomicUnicorn :: Maybe Double #
UnagiPrim Float # |
Instance details Defined in Control.Concurrent.Chan.Unagi.Unboxed.Internal Methods atomicUnicorn :: Maybe Float #
UnagiPrim Int # |
Instance details Defined in Control.Concurrent.Chan.Unagi.Unboxed.Internal Methods atomicUnicorn :: Maybe Int #
UnagiPrim Word # |
Instance details Defined in Control.Concurrent.Chan.Unagi.Unboxed.Internal Methods atomicUnicorn :: Maybe Word #

# Channel operations

## Reading

readChan :: UnagiPrim a => OutChan a -> IO a #

Read an element from the chan, blocking if the chan is empty.

Note re. exceptions: When an async exception is raised during a `readChan` the message that the read would have returned is likely to be lost, even when the read is known to be blocked on an empty queue. If you need to handle this scenario, you can use `readChanOnException`.

readChanOnException :: UnagiPrim a => OutChan a -> (IO a -> IO ()) -> IO a #

Like `readChan` but allows recovery of the queue element which would have been read, in the case that an async exception is raised during the read. To be precise exceptions are raised, and the handler run, only when `readChanOnException` is blocking.

The second argument is a handler that takes a blocking IO action returning the element, and performs some recovery action. When the handler is called, the passed `IO a` is the only way to access the element.

tryReadChan :: UnagiPrim a => OutChan a -> IO (Element a, IO a) #

Returns immediately with:

- an ``Element` a` future, which returns one unique element when it becomes available via `tryRead`.
- a blocking `IO` action that returns the element when it becomes available.

Note: This is a destructive operation. See `Element` for more details.

If you're using this function exclusively you might find the implementation in Control.Concurrent.Chan.Unagi.NoBlocking.Unboxed is faster.

Note re. exceptions: When an async exception is raised during a `tryReadChan` the message that the read would have returned is likely to be lost, just as it would be when raised directly after this function returns.

newtype Element a #

An `IO` action that returns a particular enqueued element when and if it becomes available.

Each `Element` corresponds to a particular enqueued element, i.e. a returned `Element` always offers the only means to access one particular enqueued item. The value returned by `tryRead` moves monotonically from `Nothing` to `Just a` when and if an element becomes available, and is idempotent at that point.

So for instance:

       (in, out) <- newChan
       (el, _) <- tryReadChan out  -- READ FROM EMPTY CHAN
       writeChan in "msg1"
       writeChan in "msg2"
       readChan out        -- RETURNS "msg2"
       tryRead el          -- RETURNS "msg1" (which would otherwise be lost)

Constructors

Element |
Fields tryRead :: IO (Maybe a)

#### Instances

Instances details

Alternative Element # |
Instance details Defined in Control.Concurrent.Chan.Unagi.NoBlocking.Types Methods empty :: Element a # (<|>) :: Element a -> Element a -> Element a # some :: Element a -> Element [a] # many :: Element a -> Element [a] #
Applicative Element # |
Instance details Defined in Control.Concurrent.Chan.Unagi.NoBlocking.Types Methods pure :: a -> Element a # (<*>) :: Element (a -> b) -> Element a -> Element b # liftA2 :: (a -> b -> c) -> Element a -> Element b -> Element c # (*>) :: Element a -> Element b -> Element b # (<*) :: Element a -> Element b -> Element a #
Functor Element # |
Instance details Defined in Control.Concurrent.Chan.Unagi.NoBlocking.Types Methods fmap :: (a -> b) -> Element a -> Element b # (<$) :: a -> Element b -> Element a #
Monad Element # |
Instance details Defined in Control.Concurrent.Chan.Unagi.NoBlocking.Types Methods (>>=) :: Element a -> (a -> Element b) -> Element b # (>>) :: Element a -> Element b -> Element b # return :: a -> Element a #
MonadPlus Element # |
Instance details Defined in Control.Concurrent.Chan.Unagi.NoBlocking.Types Methods mzero :: Element a # mplus :: Element a -> Element a -> Element a #
MonadFail Element # |
Instance details Defined in Control.Concurrent.Chan.Unagi.NoBlocking.Types Methods fail :: String -> Element a #
MonadFix Element # |
Instance details Defined in Control.Concurrent.Chan.Unagi.NoBlocking.Types Methods mfix :: (a -> Element a) -> Element a #

getChanContents :: UnagiPrim a => OutChan a -> IO [a] #

Return a lazy infinite list representing the contents of the supplied OutChan, much like System.IO.hGetContents.

## Writing

writeChan :: UnagiPrim a => InChan a -> a -> IO () #

Write a value to the channel.

writeList2Chan :: UnagiPrim a => InChan a -> [a] -> IO () #

Write an entire list of items to a chan type. Writes here from multiple threads may be interleaved, and infinite lists are supported.

## Broadcasting

dupChan :: InChan a -> IO (OutChan a) #

Duplicate a chan: the returned `OutChan` begins empty, but data written to the argument `InChan` from then on will be available from both the original `OutChan` and the one returned here, creating a kind of broadcast channel.