Roux.Session (roux v0.2.2)

Copy Markdown View Source

A database's life across runs: opened from the last run's manifest, committed back to it, closed.

session =
  Roux.Session.open(
    modules: [MyTool.Graph],
    manifest: "_build/dev/my_tool.manifest",
    blob: "~/.cache/my_tool/store"
  )

try do
  %{meta: meta} = Roux.Sources.sync(session.db, :file, files, session.sources)
  results = MyTool.Graph.run(session.db)
  Roux.Session.commit(session, meta, extra: summary(results))
after
  Roux.Session.close(session)
end

open/1 registers the modules (and languages) first and restores the manifest after, so a restore sees every query it may keep (Roux.Lang.Manifest.restore/2). commit/3 writes the manifest only when the run changed something it would hold — an input set, an entry computed, the sources' metadata moved — so a run that changed nothing writes nothing. The manifest leaves out what the queries say not to keep (Roux.Query's store: and transient:, with every entry that read a transient one) and retains in the blob store what it names. A small extra term goes beside it, readable without loading the manifest (read_extra/1): what a Mix compiler's diagnostics/0 returns, say.

Summary

Types

t()

An open session: its database, the manifest it came from and goes to (nil for none), its blob store (nil for none), the sources' metadata the manifest held (%{} on a cold start), and whether it restored one.

Functions

close(session)

Closes a session: drops the values the calling process cached while serving its queries, shuts its database down, and removes its blob store when it was a temporary one (Roux.Blob.temporary/0).

commit(session, sources, opts \\ [])

Writes the session's manifest, with sources as its sources' metadata, when the run changed anything it holds: an input set or removed, an entry computed, or other sources' metadata than it restored. A session that restored nothing always writes. Returns whether it wrote, and the session as committed: committing it again writes only what changed since.

files(manifest)

The files a Mix compiler reports as its manifests for a session's manifest at manifest: the manifest and its extra sidecar.

open(opts \\ [])

Opens a session.

read_extra(manifest)

The extra term a session committed beside the manifest at manifest (commit/3), or :error when there is none, or it does not decode.

Types

t()

@type t() :: %Roux.Session{
  blob: Roux.Blob.t() | nil,
  db: Roux.Database.t(),
  manifest: Path.t() | nil,
  restored?: boolean(),
  revision: Roux.Revision.revision(),
  sources: map(),
  writes: non_neg_integer()
}

An open session: its database, the manifest it came from and goes to (nil for none), its blob store (nil for none), the sources' metadata the manifest held (%{} on a cold start), and whether it restored one.

Functions

close(session)

@spec close(t()) :: :ok

Closes a session: drops the values the calling process cached while serving its queries, shuts its database down, and removes its blob store when it was a temporary one (Roux.Blob.temporary/0).

commit(session, sources, opts \\ [])

@spec commit(t(), map(), keyword()) :: {:written | :unchanged, t()}

Writes the session's manifest, with sources as its sources' metadata, when the run changed anything it holds: an input set or removed, an entry computed, or other sources' metadata than it restored. A session that restored nothing always writes. Returns whether it wrote, and the session as committed: committing it again writes only what changed since.

Options

  • :extra — a small term to keep beside the manifest (read_extra/1), written when it differs from the one there.

files(manifest)

@spec files(Path.t()) :: [Path.t()]

The files a Mix compiler reports as its manifests for a session's manifest at manifest: the manifest and its extra sidecar.

open(opts \\ [])

@spec open(keyword()) :: t()

Opens a session.

Options

  • :modules — modules of queries (use Roux.Query) to register (Roux.Lang.register_module/2);
  • :languages — languages to register (Roux.Lang.register/2);
  • :manifest — the manifest to restore from and commit to; nil (the default) for a session that keeps nothing;
  • :blob — a Roux.Blob store, or the root of one: where store: :blob values and code versions are kept;
  • :force — true to start cold, ignoring the manifest (it is still written on commit).

read_extra(manifest)

@spec read_extra(Path.t()) :: {:ok, term()} | :error

The extra term a session committed beside the manifest at manifest (commit/3), or :error when there is none, or it does not decode.