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.

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.

Detailed stats of each data source in each round.

Rounds are 1-indexed

Pretty-print Stats.

Pretty-print RoundStats.

Pretty-print DataSourceRoundStats

Data on individual labels.

Keep track of what the current fetch round is.

Keep track of the round requests first appear in.

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 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 two ways.

• Synchronously (SyncFetch): the fetching operation is an IO () that fetches all the data and then returns.
• Asynchronously (AsyncFetch): we can do something else while the data is being fetched. The fetching operation takes an IO () as an argument, which is the operation to perform while the data is being fetched.

See syncFetch and asyncFetch for example usage.

The DataCache maps things of type f a to ResultVar a, for any f and a provided f a is an instance of Typeable. In practice f a will be a request type parameterised by its result.

See the definition of ResultVar for more details.

The implementation is a two-level map: the outer level maps the types of requests to SubCache, which maps actual requests to their results. So each SubCache contains requests of the same type. This works well because we only have to store the dictionaries for Hashable and Eq once per request type.

A new, empty DataCache.

A sink for the result of a data fetch in BlockedFetch

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 $ \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