  ^ ^                 ^ ^
=(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

Load multiple programs and enter REPL:

./flowlog program1.pl program2.pl
./flowlog -l program1.pl -l program2.pl

Explicit load flag(s):

./flowlog -l program.pl
./flowlog --load program1.pl

Fast startup (skip RC file):

./flowlog -f
./flowlog --fast

Run a one-shot query

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

Query against an empty program:

./flowlog -g "goal."

System args vs app args

System flags are parsed only before the first positional file.
After the first positional file, existing regular-file tokens start a new file segment.
Tokens between file segments are application argv for that segment/file.

Read application argv from Prolog:

?- current_prolog_flag(argv, Argv).

Flowlog returns Argv as a list of Prolog strings (for example ["-p","123","--help"]). When called from a predicate defined in a loaded file, argv resolves to that file segment’s args. At the top level (for example ?- current_prolog_flag(argv, A).), it resolves to the default segment (first positional file, or [] if none).

Examples:

./flowlog -g "run." file.pl -g localhost
# system query is: run.
# application argv for file.pl is: ["-g","localhost"]

./flowlog --engine tree proxy.pl --path=/tmp/proxy.conf https_proxy.pl --path=/tmp/https.conf
# argv for proxy.pl is: ["--path=/tmp/proxy.conf"]
# argv for https_proxy.pl is: ["--path=/tmp/https.conf"]

Thread count

Override the worker-thread count:

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

Aliases accepted by the binary:

--threads
--cpus
--cpuprocs

Engine selection

Select the execution engine (SUBSECTION 26.1):

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

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 -g "goal." program.pl

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 -g "goal." program.pl

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

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

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

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

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

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

--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 -g "goal." program.pl

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, the REPL prints the first 5 answers automatically. After that: SPACE/;/n requests 5 more, a streams all, w/x prints full saved answers, and Enter/. stops enumeration with ....
Ctrl-X prints the full saved answers from the previous query and keeps the current input line.
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.
expand. (print full saved answers from the previous query)
solutions(X). (replay saved answers one-by-one)

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)

Compile-time depth limits

Flowlog also supports compile-time depth-limit overrides in SECTION 01:

FLOWLOG_DEPTH_LIMIT - internal term/goal traversal depth limit (0 means unlimited; default 0)
FLOWLOG_SOLVE_DEPTH_LIMIT - solver goal-stack depth limit (0 means unlimited; default 0)
FLOWLOG_TRACE_MAX_DEPTH - trace frame depth cap (0 means unlimited; default 0)

Example:

cc -O2 -Wall -Wextra -pthread \
  -DFLOWLOG_DEPTH_LIMIT=4096 \
  -DFLOWLOG_SOLVE_DEPTH_LIMIT=200000 \
  flowlog.c -lm -o flowlog

History

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

RC startup file

FLOWLOG_RC_FILE - startup file path loaded at process start (SUBSECTION 26.3)
- Default: ~/.flowlogrc
- Missing file is ignored (no file is created)
-f / --fast skips RC loading
-l / --load loads one file per occurrence after RC
System CLI flags must appear before the first positional file.
After the first positional file, existing regular-file tokens begin new file segments.
Tokens between file segments are per-file application argv (current_prolog_flag(argv, A)), as a list of strings.

RC side-effect settings must be written as directives so they execute at load time, for example:

:- set_prolog_flag(flowlog_engine, wam).

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)
flowlog_parallel_max_depth runtime default:
- computed once at program start from effective thread count (--threads, FLOWLOG_N_CPUPROC, or auto-detect): max(24, 3 * threads), capped by compile-time FLOWLOG_DEFAULT_PARALLEL_MAX_DEPTH (default cap 128).
- with --threads 8, this resolves to 24.
- later profile toggles (flowlog_parallel_profile) do not overwrite an explicitly set flowlog_parallel_max_depth.

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)