  ^ ^                 ^ ^
=(o.o)=  ~byakuren  =(o.o)=
  m m                 m m

Flowlog CLI and REPL (`flowlog.c`)

This document describes the Flowlog command-line interface and REPL behavior for the binary built from flowlog.c.

The Flowlog binary is:

./flowlog

Code references (section markers in flowlog.c):

CLI parsing/flags and main entry: SECTION 26 (SUBSECTIONS 26.1/26.3)
REPL history and line editing: SUBSECTION 26.2
Signal handling and stack tracing: SECTION 04 (SUBSECTION 04.3) and SECTION 06 (SUBSECTIONS 06.2/06.3)

CLI usage

Show help (SUBSECTION 26.1):

./flowlog --help

Show version (SUBSECTION 26.1):

./flowlog --version

Interactive REPL (default)

Empty program:

./flowlog

Load a program and enter REPL:

./flowlog program.pl

You can also use the explicit file flag:

./flowlog -f program.pl

Run a one-shot query

./flowlog program.pl -g "goal."

Query against an empty program:

./flowlog -g "goal."

Thread count

Override the worker-thread count:

./flowlog --threads 12 program.pl -g "goal."

Aliases accepted by the binary:

--threads
--cpus
--cpuprocs

Engine selection

Select the execution engine (SUBSECTION 26.1):

./flowlog --engine wamvm program.pl -g "goal."

Values:

wamvm - default bytecode VM for compiled clause bodies (still sharing the same unifier/built-ins as wam); falls back to wam when the program/query uses unsupported features (see WAM_ROADMAP.md) (SECTIONS 18/24)
wam - WAM-lite engine (falls back to the interpreter if needed) (SECTION 23)
interp / tree - direct interpreter (“tree-walking”) (SECTION 22)

If wam or wamvm is requested but Flowlog falls back to the interpreter, it prints a warning to stderr by default (SECTION 24). Disable this warning with:

FLOWLOG_WARN_ENGINE_FALLBACK=0 (SUBSECTION 26.1)

To ensure the wamvm engine does not fall back to the WAM-lite solver for unsupported programs/queries, set (SECTION 24):

FLOWLOG_WAMVM_REQUIRE_VM=1 (exits with code 2 if unsupported built-ins are used) (SECTION 24)

You can also introspect which engine actually ran a query (SECTIONS 22/23/24):

?- current_prolog_flag(flowlog_engine_active, Engine).

Parallel profile

Select a parallelism profile (equivalent to set_prolog_flag(flowlog_parallel_profile, ...)) (SUBSECTION 26.1 and SECTIONS 22/23/24):

./flowlog --parallel-profile fast program.pl -g "goal."

Values:

off - sequential behavior (Flowlog parallel features disabled)
iso - enable parallelism but keep ordered solution commit
fast - enable all parallel features and allow unordered OR-par for maximum throughput

Defaults (unless your program overrides flags with :- set_prolog_flag/2 directives):

engine: wamvm (SECTION 25)
profile: fast (SECTION 25)

Tracing

Enable Prolog-style trace ports (CALL/EXIT/REDO/FAIL) on stderr (SUBSECTION 26.1):

./flowlog --trace program.pl -g "goal."

Enable internal (C/VM) tracing on stderr (SUBSECTION 26.1):

./flowlog --itrace program.pl -g "goal."

Only emit internal trace lines when C stack usage reaches a new peak (SUBSECTION 26.1 and SECTION 06):

./flowlog --itrace-watermark program.pl -g "goal."

Throw a catchable exception before a hard C-stack SIGSEGV overflow (SUBSECTION 26.1 and SECTION 06):

./flowlog --cstack-limit 32MB program.pl -g "goal."

--cstack-limit accepts raw bytes or a K/M/G suffix (optionally followed by B), for example 65536, 64K, 8MB.

If you still hit a SIGSEGV (for example due to a true C stack overflow), you can enable a best-effort crash dump of the last recorded trace frames (SUBSECTION 26.1 and SECTION 06):

./flowlog --segv-trace program.pl -g "goal."

Notes:

Trace output is non-interactive (it prints ports/log lines; it does not prompt).
With parallelism enabled, trace output from multiple worker threads may interleave; for deterministic debugging use --threads 1 --parallel-profile off (SECTION 21 and SUBSECTION 26.1).

REPL behavior

Prompts and non-interactive mode

If stdin/stdout are a TTY, Flowlog prints a banner and a ?- prompt (SECTION 26).
If stdin/stdout are not a TTY, Flowlog reads from stdin without prompts/banners (useful for scripting) (SECTION 26).
On a TTY, after each solution: ; requests the next, f prints the next 5, a streams all, and Enter stops.
Ctrl-C interrupts the current query and returns to the prompt (the loaded program remains in memory) (SUBSECTION 04.3 and SECTION 26).
Ctrl-T (BSD SIGINFO) prints a live status report (current predicate, stack, parallel state, memory counters) (SUBSECTION 04.3 and SECTION 06).

Meta-commands

The REPL supports a small set of meta-commands (single-line, no trailing . required):

:help
:load <file.pl>
:reload (reload last loaded program)

And the ISO-style “regular” commands:

help.
halt. / quit.

Loading code interactively

The REPL supports the common Prolog top-level convenience:

[file]. (and [file1,file2].) - load one or more source files (consult-style); this replaces the currently loaded program, similar to :load.

Use one of:

Start the REPL with a file argument: ./flowlog program.pl
:load program.pl (replaces the currently loaded program)
:reload (reload the last :load file)

Output format

Flowlog prints output in a stable, test-friendly format (SECTION 17):

Each solution on its own line: X = 1, Y = foo
Success with no bindings: true
Failure: false

Environment variables

Tracing / stack debugging

FLOWLOG_TRACE - enable --trace by default (SUBSECTION 26.1)
FLOWLOG_ITRACE - enable --itrace by default (SUBSECTION 26.1)
FLOWLOG_ITRACE_WATERMARK - enable --itrace-watermark by default (SUBSECTION 26.1 and SECTION 06)
FLOWLOG_CSTACK_LIMIT - same as --cstack-limit (SUBSECTION 26.1 and SECTION 06)
FLOWLOG_SEGV_TRACE - install a SIGSEGV handler that dumps last trace frames (best-effort) (SUBSECTION 06.3 and SUBSECTION 26.1)

Main stack sizing (Linux / small RLIMIT_STACK)

Some systems (notably Linux) default to a small main-thread stack (often 8 MiB). Deep interpreter recursion (for example when running quad tests in --engine tree) can exhaust this stack.

Flowlog can automatically run its main loop on a dedicated pthread with a larger stack:

Default behavior: auto-enable when RLIMIT_STACK is smaller than ~16 MiB (unless FLOWLOG_STACK_BOOST overrides it) (SUBSECTION 26.3)
Default boosted stack size: max(64MB, 8 * RLIMIT_STACK) (page-aligned)
FLOWLOG_STACK_BOOST=0|off|false - disable main-stack boost (SUBSECTION 26.3)
FLOWLOG_STACK_BOOST=1|on|true|force - enable/force main-stack boost (SUBSECTION 26.3)
FLOWLOG_MAIN_STACK_SIZE - override the boosted pthread stack size (supports K/M/G suffixes like 64MB) (SUBSECTION 26.3)

History

FLOWLOG_HISTORY_FILE - history file path (TTY REPL only) (SUBSECTION 26.2)
- Default: ~/.flowlog_history

Parallelism tuning

FLOWLOG_N_CPUPROC - default worker-thread count (SUBSECTION 04.2)
FLOWLOG_ORPAR_MAX_WORKERS - cap internal OR-par pthread workers (SUBSECTION 04.3)
FLOWLOG_ORPAR_STACK_SIZE - override OR-par pthread stack size (bytes) (SUBSECTION 04.3)
FLOWLOG_POOL_LOCAL_ALLOC - prefer process-local allocations for query-temporary memory (can improve OR-par scalability) (SUBSECTION 09.3)

Debugging OR-par

FLOWLOG_DEBUG_ORPAR - 0/off, 1 (big choicepoints), or 2/all (SUBSECTION 06.4)
FLOWLOG_DEBUG_ORPAR_LOG - file path to append OR-par debug logs (SUBSECTION 06.4)

Exit codes

0 - success
1 - load or runtime failure
2 - CLI usage / argument errors

Flowlog CLI and REPL (flowlog.c)