# roux v0.2.2 - Table of Contents

A framework for building incremental mix compilers

## Modules

- [Roux](Roux.md): A framework for building incremental mix compilers.

- [Roux.Blob](Roux.Blob.md): A content-addressed store on disk, safe to share between OS processes:
large values kept by digest, an action cache, verifying traces, and
scratch directories, with a garbage collector that never takes what a
reader is using.
- [Roux.Blob.Trace](Roux.Blob.Trace.md): Verifying traces: a value kept with what computing it observed, reused
only while every observation still holds.
- [Roux.Cancellation](Roux.Cancellation.md): Process-based cancellation of in-flight query computations.
- [Roux.Code](Roux.Code.md): The code a computation runs, named by a digest: what a query's code
version is made of (`Roux.Query`'s `code:` option).
- [Roux.Code.Verify](Roux.Code.Verify.md): What a computation actually runs, for a test that checks a closure
(`Roux.Code.closure/2`) against it: every module the computation
executes must be in the closure of the roots its code version is
made of, or an edit to that module would leave stale results in
place.
- [Roux.Cycle](Roux.Cycle.md): Detects cycles in the query dependency graph at runtime.
- [Roux.Database](Roux.Database.md): Central handle for all framework state.
- [Roux.Database.Heir](Roux.Database.Heir.md): Preserves ETS tables across `Roux.Database.TableOwner` crashes.
- [Roux.Database.Supervisor](Roux.Database.Supervisor.md): Supervises the ETS table ownership processes.
- [Roux.Database.TableOwner](Roux.Database.TableOwner.md): Owns all framework ETS tables during normal operation.
- [Roux.Entity](Roux.Entity.md): Tracked structs with identity that persists across revisions.
- [Roux.GC](Roux.GC.md): Garbage collection of stale memo entries and dead entities.
- [Roux.Input](Roux.Input.md): External values that form the leaves of the dependency graph.
- [Roux.Input.Definition](Roux.Input.Definition.md): Describes an input: its name and how often it changes (durability).
- [Roux.Intern](Roux.Intern.md): Bidirectional mapping from values to unique integer IDs.
- [Roux.Lang](Roux.Lang.md): Convention layer defining what it means to be a "language" in the Roux ecosystem.
- [Roux.Lang.Compiler](Roux.Lang.Compiler.md): Mix compiler integration for Roux languages.
- [Roux.Lang.LSP](Roux.Lang.LSP.md): Generic LSP server that delegates IDE features to query-based language
implementations. Built on `gen_lsp`.
- [Roux.Lang.Manifest](Roux.Lang.Manifest.md): Manifest read/write for cross-VM incremental compilation.
- [Roux.Memo](Roux.Memo.md): Memo table: the cache layer that stores query results.
- [Roux.Memo.Entry](Roux.Memo.Entry.md): A single memo table entry recording a cached query result.
- [Roux.Query](Roux.Query.md): Derived query definition and the `defquery` macro.
- [Roux.Query.Definition](Roux.Query.Definition.md): Describes a derived query: its name, the module and function that implement
it, and any additional options.
- [Roux.QueryLog](Roux.QueryLog.md): Records which queries of a database executed, were served from the
memo table, or came back unchanged (early cutoff): what an edit made
a graph recompute, for tests that assert the exact recompute set and
for harnesses that report it.
- [Roux.Revision](Roux.Revision.md): Global revision counter and per-durability-level change tracking.
- [Roux.Runtime](Roux.Runtime.md): The query execution engine.
- [Roux.Runtime.Context](Roux.Runtime.Context.md): Threaded context passed through query execution.
- [Roux.Session](Roux.Session.md): A database's life across runs: opened from the last run's manifest,
committed back to it, closed.
- [Roux.Sources](Roux.Sources.md): Files as inputs: `sync/5` brings an input keyed by file up to date
with what is on disk, reading only what may have changed.
- [Roux.Stamp](Roux.Stamp.md): A value computed from files, kept for as long as the files' stat
stamps say they have not changed: `memo/4`.
- [Roux.Telemetry](Roux.Telemetry.md): Structured event definitions for observability and debugging.
- [Roux.Test.BlobFixture](Roux.Test.BlobFixture.md): A blob store on a model file system (`Roux.Test.ModelFS`), for the
Concuerror scenarios of `test/concurrency/blob_test.ex`: the store's
directories made, the calling process entered as model OS process "1".

- [Roux.Test.BlobStress](Roux.Test.BlobStress.md): Loops run in peer VMs (separate OS processes) against one store, for
`Roux.Blob.ReplaceTest` and `Roux.Blob.VersionsTest`: each runs for
`ms` milliseconds and reports what it saw.

- [Roux.Test.GroupFixture](Roux.Test.GroupFixture.md): A database holding a fan-out over `{:upper, "a"}`, `{:upper, "b"}` or
both, as a run left it, and the input of `"a"` changed since: the
group is stale. Written directly rather than computed, to keep the
scenarios Concuerror explores short (`test/concurrency/group_test.ex`).

- [Roux.Test.ModelFS](Roux.Test.ModelFS.md): A file system in an ETS table, for the Concuerror scenarios of the
blob store (`test/concurrency/blob_test.ex`): `Roux.Blob.IO` answers a
process's operations from it once the process `enter/2`s it, so the
store's own code runs over a file system whose every step is a
scheduling point Concuerror can interleave.
- [Roux.Test.RawGate](Roux.Test.RawGate.md): Holds a race in `Roux.Blob` open: at the file operations a gate names,
it runs an action after the operation completed and before the store
sees its result. A check-then-act race in the store then happens on
every run: the gate is the other process, acting between the check and
the act.
- [Roux.Validation](Roux.Validation.md): Determines whether a cached memo entry is still valid.

- Exceptions
  - [Roux.Blob.FormatError](Roux.Blob.FormatError.md): Raised by `Roux.Blob.open!/1` for a directory holding a store of
another layout: its `FORMAT` file names another version.

  - [Roux.Blob.MissingError](Roux.Blob.MissingError.md): Raised by `Roux.Blob.fetch!/2` for a digest the store holds no entry
for: never written, collected, or found corrupt.

  - [Roux.Blob.TrustError](Roux.Blob.TrustError.md): Raised by `Roux.Blob.open!/1` (and returned by `Roux.Blob.open/1`) for
a store whose files another user could have written: a root, or its
`FORMAT` file, that the current OS user does not own or that is
writable by its group or by everyone.
  - [Roux.Cycle.Error](Roux.Cycle.Error.md): Raised when a cycle is detected in the query dependency graph.
  - [Roux.Input.NotSetError](Roux.Input.NotSetError.md): Raised when reading an input key that has never been set.

  - [Roux.Intern.UnknownIdError](Roux.Intern.UnknownIdError.md): Raised when attempting to resolve an intern ID that does not exist.

  - [Roux.Query.FormatError](Roux.Query.FormatError.md): Raised when registering a module of queries compiled against a roux
whose definition format is not this one's (`Roux.Query.format/0`):
what it generated is not what this roux reads, so none of it runs.
`format` is the module's (nil for a roux older than the stamp: 0.1
and the 0.2 development builds before it), `expected` this roux's.

## Mix Tasks

- [mix compile.roux](Mix.Tasks.Compile.Roux.md): Mix compiler task for Roux languages.
- [mix concuerror](Mix.Tasks.Concuerror.md): Runs Concuerror tests for exhaustive scheduler interleaving exploration.
- [mix roux.gen.zed](Mix.Tasks.Roux.Gen.Zed.md): Generates a Zed editor extension for Roux-powered languages.
- [mix roux.lsp](Mix.Tasks.Roux.Lsp.md): Starts the Roux LSP server over stdio.

