chp-2.0.0: An implementation of concurrency ideas from Communicating Sequential Processes

Control.Concurrent.CHP.Channels.Creation

Description

This module contains a proliferation of channel creation methods.

For most uses, newChannel is the only method needed from this module. This creates a channel for you to use. The channel will be automatically destroyed during garbage collection when it falls out of use, so there is no need to do anything to destroy it.

It is often possible for the type system to infer which channel you want when you use newChannel. If the types of the ends are known by the type system, the channel-type can be inferred. So you can usually just write newChannel, and depending on how you use the channel, the type system will figure out which one you needed.

If this gives a type error along the lines of: 

    Ambiguous type variables `r', `w' in the constraint:
      `Channel r w' arising from a use of `newChannel' at tmp.hs:3:24-33
    Probable fix: add a type signature that fixes these type variable(s)

Then you must either explicitly type the channel ends you are using, or more simply, use one of the synonyms in Control.Concurrent.CHP.Channels.Synonyms to indicate which kind of channel you are allocating.

Several other functions in this module, such as newChannelWR, newChannels and newChannelList are helpers built with newChannel to ease dealing with channel creation.

The remainder of the functions in this module are related to traces (see Control.Concurrent.CHP.Traces), and allowing the channels to show up usefully in traces: see newChannel' and ChanOpts.

The channel creation methods were refactored in version 1.5.0. Your code will only be affected if you were using the trace-related methods (for labelling the channels in traces). Instead of using oneToOneChannelWithLabel foo, you should use oneToOneChannel' $ chanLabel foo.

Synopsis

Documentation

data Chan r w a Source

A channel type, that can be used to get the ends of the channel via reader and writer

Instances

Channel r w => ChannelTuple (Chan r w a, Chan r w a) 
Channel r w => ChannelTuple (Chan r w a, Chan r w a, Chan r w a) 
Channel r w => ChannelTuple (Chan r w a, Chan r w a, Chan r w a, Chan r w a) 
Channel r w => ChannelTuple (Chan r w a, Chan r w a, Chan r w a, Chan r w a, Chan r w a) 
Channel r w => ChannelTuple (Chan r w a, Chan r w a, Chan r w a, Chan r w a, Chan r w a, Chan r w a) 

class Channel r w whereSource

A class used for allocating new channels, and getting the reading and writing ends. There is a bijective assocation between the channel, and its pair of end types. You can see the types in the list of instances below. Thus, newChannel may be used, and the compiler will infer which type of channel is required based on what end-types you get from reader and writer. Alternatively, if you explicitly type the return of newChannel, it will be definite which ends you will use. If you do want to fix the type of the channel you are using when you allocate it, consider using one of the many oneToOneChannel-like shorthand functions that fix the type.

Methods

newChannel' :: MonadCHP m => ChanOpts a -> m (Chan r w a)Source

Like newChannel but allows you to specify a way to convert the values into Strings in order to display them in the traces, and a label for the traces. If you don't use traces, you can use newChannel.

Added in version 1.5.0.

sameChannel :: r a -> w a -> BoolSource

Determines if two channel-ends refer to the same channel.

This function was added in version 1.4.0.

Instances

newChannel :: (MonadCHP m, Channel r w) => m (Chan r w a)Source

Allocates a new channel. Nothing need be done to destroy/de-allocate the channel when it is no longer in use.

This function does not add any information to the traces: see newChannel' for that purpose.

In version 1.5.0, this function was moved out of the Channel class, but that should only matter if you were declaring your own instances of that class (very unlikely).

data ChanOpts a Source

Options for channel creation; a function to show the inner data, and an optional label (both only affect tracing). These options can be passed to newChannel'.

Added in version 1.5.0.

Constructors

ChanOpts 

Fields

chanOptsShow :: a -> String
 
chanOptsLabel :: Maybe String
 

defaultChanOpts :: ChanOpts aSource

The default: don't show anything, don't label anything

Added in version 1.5.0.

chanLabel :: Show a => String -> ChanOpts aSource

Uses the Show instance for showing the data in traces, and the given label.

Added in version 1.5.0.

newChannelWR :: (Channel r w, MonadCHP m) => m (w a, r a)Source

A helper that is like newChannel but returns the writing and reading end of the channels directly.

newChannelRW :: (Channel r w, MonadCHP m) => m (r a, w a)Source

A helper that is like newChannel but returns the reading and writing end of the channels directly.

class ChannelTuple t whereSource

A helper class for easily creating several channels of the same type. The same type refers not only to what type the channel carries, but also to the type of channel (one-to-one no poison, one-to-any with poison, etc). You can write code like this: 

 (a, b, c, d, e) <- newChannels

To create five channels of the same type.

Methods

newChannels :: MonadCHP m => m tSource

Instances

Channel r w => ChannelTuple (Chan r w a, Chan r w a) 
Channel r w => ChannelTuple (Chan r w a, Chan r w a, Chan r w a) 
Channel r w => ChannelTuple (Chan r w a, Chan r w a, Chan r w a, Chan r w a) 
Channel r w => ChannelTuple (Chan r w a, Chan r w a, Chan r w a, Chan r w a, Chan r w a) 
Channel r w => ChannelTuple (Chan r w a, Chan r w a, Chan r w a, Chan r w a, Chan r w a, Chan r w a) 

newChannelList :: (Channel r w, MonadCHP m) => Int -> m [Chan r w a]Source

Creates a list of channels of the same type with the given length. If you need to access some channels by index, use this function. Otherwise you may find using newChannels to be easier.

newChannelListWithLabels :: (Channel r w, MonadCHP m) => [String] -> m [Chan r w a]Source

A helper that is like newChannelList, but labels the channels with the given list. The number of channels returned is the same as the length of the list of labels

newChannelListWithStem :: (Channel r w, MonadCHP m) => Int -> String -> m [Chan r w a]Source

A helper that is like newChannelList, but labels the channels according to a pattern. Given a stem such as foo, it names the channels in the list foo0, foo1, foo2, etc.

labelChannel :: MonadCHP m => Chan r w a -> String -> m ()Source

Labels a channel in the traces. It is easiest to do this at creation. The effect of re-labelling channels after their first use is undefined.

Added in version 1.5.0.