The Haxl monad, which does several things:

• It is a reader monad for Env, which contains the current state of the scheduler, including unfetched requests and the run queue of computations.
• It is a writer monad for WriteTree. We strongly advise these be used only for logs used for debugging. These are not memoized. Other relevant writes should be returned as function output, which is the more "functional" way.

The result of a computation is either Done with a value, Throw with an exception, or Blocked on the result of a data fetch with a continuation.

A tree of writes done during a Haxl computation. We could use a simple list, but this allows us to avoid multiple mappends when concatenating writes from two haxl computations.

Users should try to treat this data type as opaque, and prefer to use flattenWT to get a simple list of writes from a WriteTree.

A data representation of a Haxl continuation. This is to avoid repeatedly traversing a left-biased tree in a continuation, leading O(n^2) complexity for some pathalogical cases - see the "seql" benchmark in tests/MonadBench.hs. See "A Smart View on Datatypes", Jaskelioff/Rivas, ICFP'15

A synchronisation point. It either contains a value, or a list of computations waiting for the value.

The contents of a full IVar. We have to distinguish exceptions thrown in the IO monad from exceptions thrown in the Haxl monad, so that when the result is fetched using getIVar, we can throw the exception in the right way.

A completed request from a data source, containing the result, and the IVar representing the blocked computations. The job of a data source is just to add these to a queue (completions) using putResult; the scheduler collects them from the queue and unblocks the relevant computations.

The data we carry around in the Haxl monad.

Initialize an environment with a StateStore, an input map, a preexisting DataCache, and a seed for the random number generator.

Initializes an environment with StateStore and an input map.

A new, empty environment.

Extracts data from the Env.

Returns a version of the Haxl computation which always uses the provided Env, ignoring the one specified by runHaxl.

A list of computations together with the IVar into which they should put their result.

This could be an ordinary list, but the optimised representation saves space and time.

Throw an exception in the Haxl monad

Catch an exception in the Haxl monad

Catch exceptions that satisfy a predicate

Returns Left e if the computation throws an exception e, or Right a if it returns a result a.

Like try, but lifts all exceptions into the HaxlException hierarchy. Uses unsafeToHaxlException internally. Typically this is used at the top level of a Haxl computation, to ensure that all exceptions are caught.

Dump the contents of the cache as Haskell code that, when compiled and run, will recreate the same cache contents. For example, the generated code looks something like this:

loadCache :: GenHaxl u w ()
loadCache = do
  cacheRequest (ListWombats 3) (Right ([1,2,3]))
  cacheRequest (CountAardvarks "abcabc") (Right (2))

Dump the contents of the cache as Haskell code that, when compiled and run, will recreate the same cache contents. Does not take into account the writes done as part of the computation.

Takes the name and type for the resulting function as arguments.

Under ordinary circumstances this is unnecessary; users of the Haxl monad should generally not perform arbitrary IO.

Convert exceptions in the underlying IO monad to exceptions in the Haxl monad. This is morally unsafe, because you could then catch those exceptions in Haxl and observe the underlying execution order. Not to be exposed to user code.