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

Troubleshooting (`flowlog.c`)

Code references (section markers in flowlog.c):

OR-par workers and job execution: SECTIONS 07 and 21
OR-par stack sizing and signal handling: SECTION 04 (SUBSECTION 04.3)
C-stack diagnostics and SIGSEGV tracing: SECTION 06 (SUBSECTIONS 06.2/06.3)
CLI flags and REPL behavior: SECTION 26

Stack overflows / crashes under OR-par

OR-par workers run deep recursive solver code and can overflow small pthread stacks.

Try:

Reduce worker count: --threads N (SUBSECTION 26.1)
Override stack size: FLOWLOG_ORPAR_STACK_SIZE=33554432 (32 MiB) (SUBSECTION 04.3)
Cap OR-par workers: FLOWLOG_ORPAR_MAX_WORKERS=N (SUBSECTION 04.3)
Add a soft C-stack limit to get a catchable exception instead of a hard crash: FLOWLOG_CSTACK_LIMIT=32MB (or --cstack-limit 32MB) (SECTION 06 and SUBSECTION 26.1)
Tail-call optimization in the WAMVM prevents stack growth but does not reclaim heap allocations. Arithmetic loops that create new terms (N1 is N-1) will still grow RSS until you stop the query. Scope reuse rewrites safe bound vars in tail goals; it is skipped when bound values still depend on the current scope (or packed-string tails depend on bound scope vars), to preserve correctness.
Enable internal tracing to see where stack usage spikes: --itrace-watermark (prints only on new C-stack peaks) (SECTION 06 and SUBSECTION 26.1)
If it still SIGSEGVs, enable a best-effort crash dump of the last trace frames: FLOWLOG_SEGV_TRACE=1 (or --segv-trace) (SUBSECTION 06.3 and SUBSECTION 26.1)
For more readable traces, disable parallelism: --threads 1 --parallel-profile off (SUBSECTION 26.1)

Stack overflows on Linux / small `ulimit -s`

Many Linux distributions default to a small main-thread stack (often 8 MiB, see ulimit -s). Deep interpreter recursion (for example make quad, which runs --engine tree) can overflow this stack.

Options:

Increase the shell stack limit before running Flowlog (affects the main thread): ulimit -s unlimited (or a large value)
Prefer WAM engines for most workloads: --engine wamvm (default) or --engine wam (SUBSECTION 26.1)
Use Flowlog’s main-stack boost, which runs the main loop on a pthread with a larger stack (SUBSECTION 26.3):
- FLOWLOG_STACK_BOOST=force (force-enable)
- FLOWLOG_STACK_BOOST=off (disable)
- FLOWLOG_MAIN_STACK_SIZE=64MB (override the boosted stack size)

By default, Flowlog auto-enables this boost when it detects a small RLIMIT_STACK (below ~16 MiB).

“It’s only using one core”

Parallelism is enabled by default (flowlog_parallel_profile=fast) (SECTION 25).

If you only see one core in use, check:

Your program did not turn parallelism off via directives (SECTION 25):
- :- set_prolog_flag(flowlog_parallel_profile, off).
- :- set_prolog_flag(flowlog_parallel_or, off).
You are not running with --threads 1 (or FLOWLOG_N_CPUPROC=1) (SUBSECTION 26.1 and SUBSECTION 04.2).
The workload actually has large enough choicepoints for OR-par to help:
- Flowlog only spawns OR-par for “big” alternative sets (by default, very small choicepoints stay sequential to avoid overhead) (SECTION 21).
- Enable OR-par logs (FLOWLOG_DEBUG_ORPAR=all) to see whether work is being spawned (SUBSECTION 06.4).
You are not benchmarking on the interpreter engine by accident:
Prefer --engine wamvm (default) or try --engine wam for the WAM-lite engine (SUBSECTION 26.1).

Also confirm Flowlog sees your CPU count (SUBSECTION 04.2):

FLOWLOG_N_CPUPROC is not set to 1
you did not pass --threads 1

Notes:

Some workloads do not have large enough choicepoints for OR-par to help.
For ordered mode (flowlog_parallel_profile=iso), Flowlog may limit parallelism to preserve classic enumeration order (SECTION 21 and SECTION 25).
OR-par is heuristic-driven; enable debug logs to confirm spawning (SUBSECTION 06.4):
- FLOWLOG_DEBUG_ORPAR=1 (or 2) and optionally FLOWLOG_DEBUG_ORPAR_LOG=/tmp/flowlog_orpar.log

REPL editing keys don’t work

The line editor is enabled only when stdin/stdout are TTYs (SUBSECTION 26.2). If you run the REPL via redirected input/output, Flowlog falls back to plain line reads (SECTION 26).

History file issues

History is written to (SUBSECTION 26.2):

~/.flowlog_history by default

Override with:

FLOWLOG_HISTORY_FILE=/path/to/file

“My terminal output is staircasing / newlines look wrong”

If your terminal looks like output is indented further and further to the right, your terminal may have been left in a bad termios state after a crash.

Fix:

reset

“`[file].` doesn’t load my program”

Flowlog supports the common top-level consult shorthand, but it only works when the file can be resolved on disk (SECTION 25 and SECTION 26).

Try:

?- [program]. (Flowlog will also try program.pl if program is missing)
?- ['path/with/slash/program.pl']. (quote paths with spaces or special characters)
Or use :load program.pl / ./flowlog program.pl

Parse and syntax errors (with context)

When Flowlog fails to parse a program, it reports the unexpected token (or expected token), file/line/column, and a one-line source excerpt with a caret (SECTION 10 and SECTION 25):

flowlog: fatal error (240): flowlog: unexpected token while parsing term: ) (TOK_RPAREN)
  at program.pl:1:6
  expected one of: '(', '[', atom, string, number, variable
  (')' closes a group/call; a term was expected before it)
  1 | p :- ).
    |      ^

For read/1,2 and read_term/2,3, lexer syntax errors (for example illegal_character_escape) also print the same kind of file context to stderr, in addition to throwing the usual error(syntax_error(...), read_term/N) exception (SECTION 17):

flowlog: syntax error: illegal_character_escape
  at data.term:1:3
  (invalid character escape in a quoted atom/string)
  1 | "a\q".
    |   ^

Troubleshooting (flowlog.c)