Network.Mom.Patterns.Enumerator

Enumerators for basic patterns

Enumerators

Enumerators generate streams and pass chunks of the stream for further processing to Iteratees. The Enumerator-Iteratee abstraction is very powerful and is by far not discussed exhaustively here. For more details, please refer to the documentation of the Enumerator package.

The Patterns package provides a small set of enumerators that may be useful for many messaging patterns. Enumerators are split into raw enumerators, which can be used with patterns under direct control of application code such as Client, Pub and Peer, and Fetchers, which are used with services, i.e. withServer and withPeriodicPub.

Raw Enumerators

enumWith :: (i -> IO (Maybe o)) -> i -> Enumerator o IO ()

Calls an application-defined getter function until this returns Nothing; if the getter throws an exception, the enumerator returns Error.

enumFor :: (Int -> i -> IO o) -> (Int, Int) -> i -> Enumerator o IO ()

Calls the application-defined getter function n times; The enumerator receives a pair (Int, Int), where the first integer is a counter and the second is the upper bound. n is defined as snd - fst, i.e. the counter is incremented until it reaches the value of the bound. The counter must be a value less than the bound to avoid protocol errors, i.e. the getter must be called at least once. The current value of the counter and additional input are passed to the getter. if the getter throws an exception, the enumerator returns Error.

once :: (i -> IO o) -> i -> Enumerator o IO ()

Calls the application-defined getter function once; the enumerator must return a value (the result type is not Maybe), otherwise, the sending iteratee has nothing to send which would most likely result in a protocol error. if the getter throws an exception, the enumerator returns Error.

just :: o -> Enumerator o IO ()

Passes just the input value to iteratee;

 just "hello world"

hence, reduces to just hello world sent over the wire.

Fetchers

type Fetch i o = Context -> Parameter -> i -> Enumerator o IO ()

Enumerator to process data segments of type o; receives the Context, the control parameter and an input of type i; Fetch is used by Servers that receive requests of type i and produce an outgoing stream with segments of type o.

type Fetch_ o = Fetch () o

A variant of Fetch without input

type FetchHelper i o = Context -> Parameter -> i -> IO (Maybe o)

A function that may be used with some of the fetchers; The helper returns Nothing to signal that no more data are available and Just o to continue the stream. FetchHelpers are used with Servers that receive requests of type i. The function receives the Context, the conrol parameter and an input of type i;

type FetchHelper' i o = Context -> Parameter -> i -> IO o

A variant of FetchHelper that returns type o instead of Maybe o. Please note that ' does not mean strict, here; it just means that the result is not a Maybe.

type FetchHelper_ o = FetchHelper () o

A variant of FetchHelper without input

type FetchHelper_' o = FetchHelper' () o

A variant of FetchHelper_ that returns type o instead of Maybe o. Please note that ' does not mean strict, here; it just means that the result is not a Maybe.

fetcher :: FetchHelper i o -> Fetch i o

Calls the application-defined FetchHelper until it returns Nothing; note that the FetchHelper shall return at least one Just value to avoid a protocol error. If the FetchHelper throws an exception, the fetcher returns Error.

fetcher_ :: FetchHelper_ o -> Fetch_ o

A variant of fetcher without input;

fetch1 :: FetchHelper' i o -> Fetch i o

Calls the application-defined FetchHelper' once; If the FetchHelper' throws an exception, the fetcher returns Error.

fetch1_ :: FetchHelper_' o -> Fetch_ o

A variant of fetch1 without input;

fetchFor :: (Context -> Parameter -> Int -> i -> IO o) -> (Int, Int) -> Fetch i o

Calls the application-defined getter n times; The getter is a variant of FetchHelper' with the current value of the counter as additional argument. For more details, refer to enumFor.

fetchFor_ :: (Context -> Parameter -> Int -> () -> IO o) -> (Int, Int) -> Fetch_ o

A variant of fetchFor without input

fetchJust :: o -> Fetch i o

Passes just the input value to the iteratee;

 fetchJust "hello world"

hence, reduces to just "hello world" sent over the wire. Note that the input i is ignored.

fetchJust_ :: o -> Fetch_ o

A variant of fetchJust without input

listFetcher :: Fetch [o] o

Calls the iteratee for each element of the input list

listFetcher_ :: [o] -> Fetch_ o

A variant of listFetcher for services without input; the list, in this case, is passed as an additional argument to the fetcher.

Iteratees

Iteratees process chunks of streams passed in by an enumerator. The Enumerator-Iteratee abstraction is very powerful and is by far not discussed exhaustively here. For more details, please refer to the documentation of the Enumerator package.

The Patterns package provides a small set of iteratees that may be useful for many messaging patterns. Iteratees are split into raw iteratees, which can be used with patterns under direct control of application code such as Client, Pub, Peer and, for obtaining the request, withServer, and Dumps, which are used with services, i.e. withSub and withPuller.

Raw Iteratees

one :: i -> Iteratee i IO i

Returns one value of type i; if the enumerator creates a value, this value is returned; otherwise, the input value is returned.

mbOne :: Iteratee i IO (Maybe i)

Returns one value of type Maybe i; equal to head

toList :: Iteratee i IO [i]

Returns a list containing all chunks of the stream; equal to consume; note that this iteratee causes a space leak and is not suitable for huge streams or streams of unknown size.

toString :: String -> Iteratee String IO String

Returns a string containing all chunks of the stream intercalated with the input string, e.g.: if the stream consists of the two elements "hello" and "world"

 toString " " 

returns hello world. Note that this iteratee causes a space leak and is not suitable for huge streams or streams of unknown size.

append :: Monoid i => Iteratee i IO i

Merges the elements of a stream using mappend; if the stream is empty, append returns mempty. The type i must be instance of Monoid. Note that this iteratee causes a space leak and is not suitable for huge streams or streams of unknown size.

store :: (i -> IO ()) -> Iteratee i IO ()

Calls the application-defined IO action for each element of the stream; The IO action could, for instance, write to an already opened file, store values in an MVar or send them through a Chan to another thread for further processing. An exception thrown in the IO action is re-thrown by throwError.

Dumps

type Dump i = Context -> Parameter -> Iteratee i IO ()

Iteratee to process data segments of type i; receives the Context and the control parameter

sink :: (Context -> String -> IO s) -> (Context -> String -> s -> IO ()) -> (Context -> String -> s -> i -> IO ()) -> Dump i

Opens a data sink, dumps the stream into this sink and closes the sink when the stream terminates or when an error occurs; the first IO action is used to open the sink (of type s), the second closes the sink and the third writes one element into the sink.

sinkI :: (Context -> String -> i -> IO s) -> (Context -> String -> s -> IO ()) -> (Context -> String -> s -> i -> IO ()) -> Dump i

Variant of sink that uses the first segment of the stream as input parameter to open the sink. The first segment, which could contain a file name or parameters for an SQL query, is not written to the sink. As with sink, the sink is closed when the stream terminates or when an error occurs.

nosink :: (Context -> String -> i -> IO ()) -> Dump i

Similar to sink, but uses a data sink that is opened and closed outside the scope of the service or does not need to be opened and closed at all; examples may be services that write to MVar or Chan. nosink is implemented as a closure of store:

 nosink save ctx p = store (save ctx p)