The Haxl monad, which does several things:

• It is a reader monad for Env and IORef RequestStore, The latter is the current batch of unsubmitted data fetch requests.
• It is a concurrency, or resumption, monad. A computation may run partially and return Blocked, in which case the framework should perform the outstanding requests in the RequestStore, and then resume the computation.
• The Applicative combinator <*> explores both branches in the event that the left branch is Blocked, so that we can collect multiple requests and submit them as a batch.
• It contains IO, so that we can perform real data fetching.

Performs actual fetching of data for a Request from a DataSource.

The class of data sources, parameterised over the request type for that data source. Every data source must implement this class.

A data source keeps track of its state by creating an instance of StateKey to map the request type to its state. In this case, the type of the state should probably be a reference type of some kind, such as IORef.

For a complete example data source, see ExampleDataSource.

A functor with application, providing operations to

• embed pure expressions (pure), and
• sequence computations and combine their results (<*>).

A minimal complete definition must include implementations of these functions satisfying the following laws:

identity

pure id <*> v = v

composition

pure (.) <*> u <*> v <*> w = u <*> (v <*> w)

homomorphism

pure f <*> pure x = pure (f x)

interchange

u <*> pure y = pure ($ y) <*> u

The other methods have the following default definitions, which may be overridden with equivalent specialized implementations:

      u *> v = pure (const id) <*> u <*> v
      u <* v = pure const <*> u <*> v

As a consequence of these laws, the Functor instance for f will satisfy

      fmap f x = pure f <*> x

If f is also a Monad, it should satisfy pure = return and (<*>) = ap (which implies that pure and <*> satisfy the applicative functor laws).

We don't want the monadic mapM, because that doesn't do batching. There doesn't seem to be a way to make mapM have the right behaviour when used with Haxl, so instead we define mapM to be traverse in Haxl code.

See mapM.

See mapM.

See mapM.

An infix synonym for fmap.

See mapM.

The foldM function is analogous to foldl, except that its result is encapsulated in a monad. Note that foldM works from left-to-right over the list arguments. This could be an issue where (>>) and the `folded function' are not commutative.

       foldM f a1 [x1, x2, ..., xm]

==

       do
         a2 <- f a1 x1
         a3 <- f a2 x2
         ...
         f am xm

If right-to-left evaluation is required, the input list should be reversed.

A strict version of foldl.

The sort function implements a stable sorting algorithm. It is a special case of sortBy, which allows the programmer to supply their own comparison function.

The class of monoids (types with an associative binary operation that has an identity). Instances should satisfy the following laws:

• mappend mempty x = x

• mappend x mempty = x

• mappend x (mappend y z) = mappend (mappend x y) z

• mconcat = foldr mappend mempty

The method names refer to the monoid of lists under concatenation, but there are many other instances.

Minimal complete definition: mempty and mappend.

Some types can be viewed as a monoid in more than one way, e.g. both addition and multiplication on numbers. In such cases we often define newtypes and make those instances of Monoid, e.g. Sum and Product.

The join function is the conventional monad join operator. It is used to remove one level of monadic structure, projecting its bound argument into the outer level.

A space efficient, packed, unboxed Unicode text type.

Class for string-like datastructures; used by the overloaded string extension (-foverloaded-strings in GHC).

Throw an exception in the Haxl monad

Runs the given GenHaxl computation, and if it throws a TransientError or LogicError exception (see Haxl.Core.Exception), the exception is ignored and the supplied default value is returned instead.

Catch LogicErrors and TransientErrors and perform an alternative action

We have a 3-tiered hierarchy of exceptions, with HaxlException at the top, and all Haxl exceptions as children of this. Users should never deal directly with HaxlExceptions.

The main types of exceptions are:

InternalError

Something is wrong with Haxl core.

LogicError

Something is wrong with Haxl client code.

TransientError

Something is temporarily failing (usually in a fetch).

These are not meant to be thrown (but likely be caught). Thrown exceptions should be a subclass of one of these. There are some generic leaf exceptions defined below this, such as FetchError (generic transient failure) or CriticalError (internal failure).

For transient failures.

For errors in Haxl client code.

Generic "something was not found" exception.

Generic "something had the wrong type" exception.

Generic transient fetching exceptions.

Generic "input list was empty" exception.

Generic "passing some invalid parameter" exception.