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

Development Guide (flowlog.c)

This guide focuses on developing Flowlog in flowlog.c.

Build and run

make
./flowlog

Direct compilation is also supported:

cc -O2 -Wall -Wextra -pthread flowlog.c -lm -o flowlog

Compile-time depth defaults live in SECTION 01 of flowlog.c:

• FLOWLOG_DEPTH_LIMIT=0 (unlimited)
• FLOWLOG_SOLVE_DEPTH_LIMIT=0 (unlimited)
• FLOWLOG_TRACE_MAX_DEPTH=0 (trace storage depth cap; 0 means unlimited)

Compile-time parallel/indexing tuning defaults in SUBSECTION 01.2 and SUBSECTION 01.4 were validated with ./bench/compare_nqueens.sh 13 on a 128-core server:

• flowlog_parallel_max_depth now auto-tunes when not explicitly set:
  • effective default is computed once at program start from effective thread count (--threads, FLOWLOG_N_CPUPROC, or auto-detect): max(24, 3 * threads), capped by FLOWLOG_DEFAULT_PARALLEL_MAX_DEPTH.
  • with --threads 8, this resolves to 24; on high-core hosts it scales up to the cap.
• FLOWLOG_DEFAULT_PARALLEL_MAX_DEPTH therefore acts as the compile-time cap (default 128).

Override example:

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

Test workflow

Run the regression suite and INRIA ISO suite from this directory:

make test
make inria

Run the Quad conformance tests (QUAD - Query Using Answer Description):

make quad
make quad-wam
make quad-wamvm
make quad-tpl
make quad-scryer

# Run a single quad file
make quad tests/predicates/assertz_quad.pl

To ensure the bytecode VM (flowlog_engine=wamvm) runs the ISO suite without falling back to wam, run:

make inria-wamvm-vmonly

Directory layout

• flowlog.c - the entire runtime (single-file build)
• Makefile - minimal build rules for the binary
• tests/ - regressions and ISO suite runners
• README.md and *.md - user and developer documentation

In the full repository checkout, benchmark scripts live under ../bench/.

flowlog.c Layout Map

Flowlog uses SECTION NN and SUBSECTION NN.N headings inside flowlog.c. Documentation references these headings so you can jump directly to the implementation.

Sections (in file order):

• 1. User-Configurable Defaults
• 2. Platform & Base Types
• 3. Encoding & Text Utilities
• 4. Runtime Detection & Signals
• 5. Core Runtime Types
• 6. Runtime Globals & Diagnostics
• 7. Parallel Runtime State & Thread Pool
• 8. Streams & I/O State
• 9. Memory & Allocation
• 10. Lexer & Parser
• 11. Packed Strings & List-Like Helpers
• 12. Term Equality & List Helpers
• 13. Program DB & Indexing
• 14. Interpreter Term Ops & Unification
• 15. WAM Term Ops & Arithmetic
• 16. Term Order & Comparison
• 17. Term Writer & Reader
• 18. WAMVM Instantiation & Bytecode Model
• 19. Exceptions & Errors
• 20. Tabling
• 21. Parallel OR/AND Jobs
• 22. Interpreter Solver & Builtins
• 23. WAM-lite Solver
• 24. WAMVM VM
• 25. CLI Source Loading
• 26. CLI & REPL

Adding or adjusting built-ins

Most ISO predicates are implemented as built-ins in the solver’s goal dispatcher.

Suggested workflow:

1. Add the predicate implementation in flowlog.c (SECTIONS 22/23/24)
2. Add a regression test under tests/
3. If applicable, add a reference comparison case (Trealla/Scryer) or extend the INRIA harness inputs
4. Run:
   • the regression tests
   • the INRIA ISO suite

Coding style and PR hygiene (single file)

Even though flowlog.c is a single file, it helps to keep structure consistent:

• Prefer clear section headers (parser, term representation, unification, solver, built-ins, parallel, REPL).
• Keep helper utilities (buffers, small vectors) near their first use or in a dedicated “support” section.
• Avoid “dead” code paths; keep unused experiments behind #if 0 only temporarily.
• Add tests first when fixing conformance or regressions.

Debugging

OR-par debug logs

Enable OR-par logging:

FLOWLOG_DEBUG_ORPAR=all FLOWLOG_DEBUG_ORPAR_LOG=orpar.log \
  ./flowlog -g "goal." program.pl

Profiling

For CPU-bound problems, perf (Linux) or pmcstat (FreeBSD) can help identify hot paths in:

• unification
• indexing candidate selection
• clause instantiation (standardize-apart)
• allocation

REPL terminal state

The REPL uses termios raw mode when running on a TTY. If a crash leaves your terminal in a bad state, run:

reset