package querty

Build not yet checked
  1. Overview
  2. Docs
A simple build system for incremental and demand-driven computations

Install

dune-project
 Dependency

Authors

Maintainers

Sources

querty-0.1.0.tbz
md5=0ffa7024073872bf1bea461dea7bac80
sha512=f2a8dbf7194439fa4c0d6304247a9923db4085a1671264c8866ae41bf0e7ad39bf7db18aa75e8b41de06c1158f3a7728d3cd7c8a804fca754b7bb72d92bc010f

doc/querty/Querty/Make/index.html

Module Querty.MakeSource

Make (K) builds an engine for the query keys K.

Parameters

module K : QueryKey

Signature

Errors

Sourcetype derrived_key =
  1. | D : ('a, derrived) K.t -> derrived_key
    (*

    A derived query key with its value type hidden, so keys of different value types can be listed together in Cycle.

    *)
Sourcetype error =
  1. | MissingInput : ('a, input) K.t -> error
    (*

    A rule read an input that was never given a value with set_input. Carries the first such input encountered.

    *)
  2. | Cycle : derrived_key list -> error
    (*

    A derived query (directly or through others) fetched itself. Carries every derived query that was being computed at that point, which includes the queries forming the cycle. Order is unspecified.

    *)

Reasons a run can fail.

Database

Sourcetype db

Mutable state of the engine: input values, cached derived values with their recorded dependencies, and the current revision. Keep one db and reuse it across runs; that is what makes later runs incremental. Not safe to share between domains.

Sourceval init : unit -> db

A fresh database with no inputs set and nothing cached.

Sourceval set_input : db -> ('a, input) K.t -> 'a -> unit

set_input db key v sets input key to v.

If key already has a value equal to v (by QueryKey.values_equal) this does nothing. Otherwise the change is recorded, and the next fetch of each derived query that depends on key will recompute it.

Call it between runs, or from the top-level function passed to run. Do not call it from inside a rule.

Running

Sourceval run : db -> rules:('b. ('b, derrived) K.t -> 'b) -> (unit -> 'a) -> ('a, error) result

run db ~rules f runs f (), in which fetch and read may be used, and returns its result.

rules q computes the value of derived query q. Querty calls it only when q is not cached, or when something q used last time has changed. Rules must be deterministic and get all their inputs through read and fetch: anything else they look at (files, globals, clocks) is invisible to Querty, and changes to it will not trigger a recomputation.

On error, values computed before the error stay cached, the db remains usable, and a later run (e.g. after setting the missing input) picks up where this one left off.

Exceptions raised by f or rules propagate out of run unchanged.

Sourceval fetch : ('a, derrived) K.t -> 'a

fetch q returns the value of derived query q, recomputing it with the rules given to run only if needed. When called from a rule, records q as a dependency of that rule.

Aborts the current run with Cycle if q is already being computed.

Must be called inside run; raises Effect.Unhandled otherwise.

Sourceval read : ('a, input) K.t -> 'a

read key returns the current value of input key. When called from a rule, records key as a dependency of that rule.

Aborts the current run with MissingInput if key was never set.

Must be called inside run; raises Effect.Unhandled otherwise.