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

Process model

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

Threads and scheduling (high level)

Flowlog has one OS process and may create pthread workers when:

• 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:

• 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))
• 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:

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

Memory strategy

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

This build uses:

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

Tuning:

• FLOWLOG_POOL_LOCAL_ALLOC=on can reduce allocator contention on some OR-par workloads.

Signals and interactive control

When running in the TTY REPL:

• 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.

REPL note:

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

Output and error reporting

Flowlog prints results in a test-friendly format:

• 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