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.

Runs a Haxl computation in the given Env.

Note: to make multiple concurrent calls to runHaxl, each one must have a separate Env. A single Env must not be shared between multiple concurrent calls to runHaxl, otherwise deadlocks or worse will likely ensue.

However, multiple Envs may share a single StateStore, and thereby use the same set of datasources.

The data we carry around in the Haxl monad.

Extracts data from the Env.

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

Label a computation so profiling data is attributed to the label.

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.

The StateStore maps a StateKey to the State for that type.

Retrieves a State from the StateStore container.

Inserts a State in the StateStore container.

A StateStore with no entries.

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.

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

A data request that is not cached. This is not what you want for normal read requests, because then multiple identical requests may return different results, and this invalidates some of the properties that we expect Haxl computations to respect: that data fetches can be arbitrarily reordered, and identical requests can be commoned up, for example.

uncachedRequest is useful for performing writes, provided those are done in a safe way - that is, not mixed with reads that might conflict in the same Haxl computation.

if we are recording or running a test, we fallback to using dataFetch This allows us to store the request in the cache when recording, which allows a transparent run afterwards. Without this, the test would try to call the datasource during testing and that would be an exception.

Inserts a request/result pair into the cache. Throws an exception if the request has already been issued, either via dataFetch or cacheRequest.

This can be used to pre-populate the cache when running tests, to avoid going to the actual data source and ensure that results are deterministic.

Transparently provides caching. Useful for datasources that can return immediately, but also caches values. Exceptions thrown by the IO operation (except for asynchronous exceptions) are propagated into the Haxl monad and can be caught by catch and try.

Transparently provides caching in the same way as cacheResult, but uses the given functions to show requests and their results.

cachedComputation memoizes a Haxl computation. The key is a request.

Note: These cached computations will not be included in the output of dumpCacheAsHaskell.

Like cachedComputation, but fails if the cache is already populated.

Memoization can be (ab)used to "mock" a cached computation, by pre-populating the cache with an alternative implementation. In that case we don't want the operation to populate the cache to silently succeed if the cache is already populated.

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))

Create a new MemoVar for storing a memoized computation. The created MemoVar is initially empty, not tied to any specific computation. Running this memo (with runMemo) without preparing it first (with prepareMemo) will result in an exception.

Convenience function, combines newMemo and prepareMemo.

Store a computation within a supplied MemoVar. Any memo stored within the MemoVar already (regardless of completion) will be discarded, in favor of the supplied computation. A MemoVar must be prepared before it is run.

Continue the memoized computation within a given MemoVar. Notes:

1. If the memo contains a complete result, return that result.
2. If the memo contains an in-progress computation, continue it as far as possible for this round.
3. If the memo is empty (it was not prepared), throw an error.

For example, to memoize the computation one given by:

one :: Haxl Int
one = return 1

use:

do
  oneMemo <- newMemoWith one
  let memoizedOne = runMemo aMemo one
  oneResult <- memoizedOne

To memoize mutually dependent computations such as in:

h :: Haxl Int
h = do
  a <- f
  b <- g
  return (a + b)
 where
  f = return 42
  g = succ <$> f

without needing to reorder them, use:

h :: Haxl Int
h = do
  fMemoRef <- newMemo
  gMemoRef <- newMemo

  let f = runMemo fMemoRef
      g = runMemo gMemoRef

  prepareMemo fMemoRef $ return 42
  prepareMemo gMemoRef $ succ <$> f

  a <- f
  b <- g
  return (a + b)

Memoize a computation using an arbitrary key. The result will be calculated once; the second and subsequent time it will be returned immediately. It is the caller's responsibility to ensure that for every two calls memo key haxl, if they have the same key then they compute the same result.

Memoize a computation using its location and a Fingerprint. This ensures uniqueness across computations.

Transform a Haxl computation into a memoized version of itself.

Given a Haxl computation, memoize creates a version which stores its result in a MemoVar (which memoize creates), and returns the stored result on subsequent invocations. This permits the creation of local memos, whose lifetimes are scoped to the current function, rather than the entire request.

Transform a 1-argument function returning a Haxl computation into a memoized version of itself.

Given a function f of type a -> GenHaxl u w b, memoize1 creates a version which memoizes the results of f in a table keyed by its argument, and returns stored results on subsequent invocations with the same argument.

e.g.:

allFriends :: [Int] -> GenHaxl u w [Int]
allFriends ids = do
  memoizedFriendsOf <- memoize1 friendsOf
  concat <$> mapM memoizeFriendsOf ids

The above implementation will not invoke the underlying friendsOf repeatedly for duplicate values in ids.

Transform a 2-argument function returning a Haxl computation, into a memoized version of itself.

The 2-ary version of memoize1, see its documentation for details.

A memo key derived from a 128-bit MD5 hash. Do not use this directly, it is for use by automatically-generated memoization.

Parallel version of '(.&&)'. Both arguments are evaluated in parallel, and if either returns False then the other is not evaluated any further.

WARNING: exceptions may be unpredictable when using pAnd. If one argument returns False before the other completes, then pAnd returns False immediately, ignoring a possible exception that the other argument may have produced if it had been allowed to complete.

Parallel version of '(.||)'. Both arguments are evaluated in parallel, and if either returns True then the other is not evaluated any further.

WARNING: exceptions may be unpredictable when using pOr. If one argument returns True before the other completes, then pOr returns True immediately, ignoring a possible exception that the other argument may have produced if it had been allowed to complete.

Stats that we collect along the way.

Maps data source name to the number of requests made in that round. The map only contains entries for sources that made requests in that round.

Pretty-print Stats.

Pretty-print RoundStats.

Data on individual labels.

Flags that control the operation of the engine.

Runs an action if the tracing level is above the given threshold.

Runs an action if the report level is above the given threshold.

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 Examples.

A class of type constructors for which we can show all parameterizations.

A convenience only: package up Eq, Hashable, Typeable, and Show for requests into a single constraint.

A BlockedFetch is a pair of

• The request to fetch (with result type a)
• A ResultVar to store either the result or an error

We often want to collect together multiple requests, but they return different types, and the type system wouldn't let us put them together in a list because all the elements of the list must have the same type. So we wrap up these types inside the BlockedFetch type, so that they all look the same and we can put them in a list.

When we unpack the BlockedFetch and get the request and the ResultVar out, the type system knows that the result type of the request matches the type parameter of the ResultVar, so it will let us take the result of the request and store it in the ResultVar.

A data source can fetch data in one of four ways.

StateKey maps one type to another type. A type that is an instance of StateKey can store and retrieve information from a StateStore.

Hints to the scheduler about this data source

A sink for the result of a data fetch in BlockedFetch

Like putResult, but used to get correct accounting when work is being done in child threads. This is particularly important for data sources that are using BackgroundFetch, The allocation performed in the child thread up to this point will be propagated back to the thread that called runHaxl.

Note: if you're doing multiple putResult calls in the same thread ensure that only the last one is putResultFromChildThread. If you make multiple putResultFromChildThread calls, the allocation will be counted multiple times.

If you are reusing a thread for multiple fetches, you should call System.Mem.setAllocationCounter 0 after putResultFromChildThread, so that allocation is not counted multiple times.

Common implementation templates for fetch of DataSource.

Example usage:

fetch = syncFetch MyDS.withService MyDS.retrieve
  $ \service request -> case request of
    This x -> MyDS.fetchThis service x
    That y -> MyDS.fetchThat service y

A version of asyncFetch (actually asyncFetchWithDispatch) that handles exceptions correctly. You should use this instead of asyncFetch or asyncFetchWithDispatch. The danger with asyncFetch is that if an exception is thrown by withService, the inner action won't be executed, and we'll drop some data-fetches in the same round.

asyncFetchAcquireRelease behaves like the following:

asyncFetchAcquireRelease acquire release dispatch wait enqueue =
  AsyncFetch $ \requests inner ->
    bracket acquire release $ \service -> do
      getResults <- mapM (submitFetch service enqueue) requests
      dispatch service
      inner
      wait service
      sequence_ getResults

except that inner is run even if acquire, enqueue, or dispatch throws, unless an async exception is received.

Function for easily setting a fetch to a particular exception