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

Technical Details (flowlog.c)

This document describes the runtime model of Flowlog as built from flowlog.c. It is intended for developers and performance work.

Code references (section markers in flowlog.c):

• Thread pool and OR/AND job scheduling: SECTIONS 07 and 21 (solver entry points in SECTIONS 22/23/24)
• CPU/RAM detection and OR-par stack sizing: SECTION 04 (SUBSECTIONS 04.2/04.3)
• C-stack diagnostics and SIGSEGV tracing: SECTION 06 (SUBSECTIONS 06.2/06.3)
• Query-temporary allocators and pool allocation: SECTION 09
• Streams and term I/O: SECTION 08 and SUBSECTION 17.5
• Output formatting and term printing: SECTION 17

Process model

• Single process
• pthread-based parallelism for OR-par (default) and AND-par (when supported), controlled by Prolog flags (SECTIONS 07/21/22/23)
• No external runtime dependencies beyond libc/libm/pthreads

Threads and scheduling (high level)

Flowlog has one OS process and may create pthread workers when (SECTIONS 07/21):

• OR-parallelism is enabled and a goal produces many alternatives, or
• AND-parallelism is enabled and Flowlog identifies a safe batch of independent deterministic goals.

Thread usage is intentionally bounded (SECTION 01 and SECTION 07):

• Even in the default flowlog_parallel_profile=fast, depth cutoffs and OR-par nesting limits prevent runaway spawning.
• Use flowlog_parallel_profile=iso for ordered commits, or flowlog_parallel_profile=off to disable Flowlog parallel features.

CPU and memory auto-configuration

CPU count

Flowlog:

• Detects the online CPU count (sysconf(_SC_NPROCESSORS_ONLN)) (SUBSECTION 04.2)
• Defaults to that value for worker-thread budgets
• Allows overriding with --threads N or FLOWLOG_N_CPUPROC=N

Stack sizing

OR-par workers execute deep recursive solver code. To avoid stack overflows while also staying safe on high-core machines, Flowlog (SUBSECTION 04.3):

• Chooses a default pthread stack size based on detected physical memory and worker count
• Allows an explicit override via FLOWLOG_ORPAR_STACK_SIZE

Some systems also default to a small main thread stack (for example, Linux often defaults to 8 MiB). When the interpreter engine runs deep recursive goals (notably --engine tree), this can overflow the main stack. Flowlog can optionally run its main loop on a dedicated pthread with a larger stack when RLIMIT_STACK is small; see FLOWLOG_STACK_BOOST and FLOWLOG_MAIN_STACK_SIZE in CLI.md (SUBSECTION 26.3).

Memory strategy

Flowlog’s core solver allocates many short-lived objects (terms, environments, temporary vectors) (SECTION 09).

This build uses:

• A query-scoped “temporary allocator” that can release memory on choicepoint rollback (SUBSECTION 09.1)
• A process-local arena allocator for fast small allocations (when enabled) (SUBSECTION 09.1)
• Process-lifetime allocations for program state and caches (SECTION 13)

Tuning:

• FLOWLOG_POOL_LOCAL_ALLOC=on can reduce allocator contention on some OR-par workloads (SUBSECTION 09.3).

Signals and interactive control

When running in the TTY REPL (SUBSECTION 04.3 and SECTION 26):

• Ctrl-C interrupts the current query and returns to the prompt (the loaded program stays in memory).
• Ctrl-T (BSD SIGINFO) prints a live status report (predicate, depth, parallel flags, memory counters).
• Ctrl-D exits the REPL when pressed at an empty prompt (EOF).

When not a TTY (piped input), Ctrl-C/Ctrl-T behavior depends on your shell/terminal and may not be delivered to Flowlog.

I/O and streams

Flowlog uses process-local FILE* streams and implements the ISO stream predicates directly (SECTION 08 and SUBSECTION 17.5).

REPL note:

• Prompts/banners are printed only when stdin/stdout are TTYs.

Output and error reporting

Flowlog prints results in a test-friendly format (SECTION 17):

• true / false
• variable bindings like X = 1, Y = foo
• exceptions as error(...) terms

For scripting, treat stdout as the primary “transcript” stream.

Debugging OR-parallelism

Environment variables:

• FLOWLOG_DEBUG_ORPAR - logging level
• FLOWLOG_DEBUG_ORPAR_LOG - file path to append logs

These logs are intended to help identify:

• Where OR-par is being spawned (predicate/arity, depth)
• Whether cut/exception cancellation is happening
• Worker/chunk sizing choices