_______        _______ __   _  ______
     |______ |      |______ | \  | |  ____
     |       |_____ |______ |  \_| |_____|


    User Manual


    Version: 9


I. Introduction

This document describes an implementation of the "FLENG" programming
language as described in [1]. FLENG is a very minimal and low-level
committed-choice concurrent logic language descending from 
Concurrent Prolog.

The implementation described here provides a FLENG compiler that
generates assembly language for x86-64, ARM and RISCV machines on UNIX
or BSD systems. Additionally a front end for "Flat Guarded Horn
Clauses" (FGHC)[2] and "Strand"[5] is provided, which are slightly higher 
level and more convenient languages.


II. Usage

The compiler is invoked by using the "fleng" driver script:

    fleng [-Vwhkdcp] [CCOPT ...] [-m MODULE] [-I DIRECTORY] FILENAME 
      [-o OUTFILE] [OBJECTS ...]

The script takes FLENG, Strand or FGHC source files and generates 
assembler, binary object files or executables. The following command line 
options are supported:

  -V        
        Print version and exit.

  -w
        Disable compiler warnings.

  -k
        Keep intermediate files.

  -c
        Compile to object file, do not create an executable.

  -p
        Generate profiling information.

  -cflags
        Output C compiler options suitable for compiling C code 
        interfacing to FGHC/FLENG.

  -libs
        Output libraries needed to be linked to compiled FGHC/FLENG
        code.

  -m MODULE 
        Specifies the name of the compiled module. If no module name
        is given the module name defaults to "" (empty), which
        designates a main module.

  -I DIRECTORY
        Prepend list of directories searched when locating files
        accessed via the "include" declaration. The default include
        directory is ".".

  -o OUTFILE 
        Produce OUTFILE and exit. Depending on the file extension,
        the compilation process will stop after generating a FLENG
        source file (.fl or .fleng) an assembler file (.s), a binary
        object file (.o) or an executable (any other extension).
        As default output filename the basename of the source file
        is given and an executable file is created.

  -d
        Enable debug information, which shows slightly more information
        in debug logs and enables some additional error checking.

  -h
        Show usage information.

Binary object files can be linked together to produce executables
consisting of multiple compiled modules. The "fleng" driver accepts
*.o and *.a files on the command line and links them to any generated
executable. To compile an executable program, one main module must
be given when linking.

If the source file name has an .fl or .fleng extension, then the
"fleng" driver assumes it contains FLENG code. In all other cases
the file is considered to be an FGHC or Strand source file.

The compiler options are also documented in the fleng(1) manual page.

Generated wrapper code using the "foreign/1" declaration is detected
and compiled automatically, when binary files are produced.

All compiled executables accept a number of run-time command line
options to enable debugging output and override internal settings:

    <program> [+HELP] [+VERSION] [+LOG <mask>] [-LOGX <mask>] 
      [+HEAP <heapsize>] [+GOALS <maxgoals>] [+TIMESLICE <ticks>] 
      [+LOGFILE <filename>] [+THREADS <number>] [+STATS <mask>] 
      [+STAT_TICKS <number>] [+HEAPSTATS <mask>] [+PROFILE <filename>]
      [--] ...

+VERSION
    Show version with which this executable was built.

+LOG <mask>
    Enable logging for all threads specified by <mask>, where bit 1
    corresponds to thread 1 and so on.

+LOGX <mask>
    Enable explicit logging with "log/1" for all threads specified 
    by <mask>, where bit 1 corresponds to thread 1 and so on.

+HEAP <heapsize>
    Set default heap size for each thread in bytes. The default size
    is 1000000 bytes. The value may be suffixed by "k", "m" or "g".

+GOALS <maxgoals>
    Set the default number of goals a thread can have active at the
    same time. The default number is 10000. The value may be suffixed 
    by "k", "m" or "g".

+LOGFILE <filename>
    Specifies the location of the log file where debug information
    is written to, if logging is enabled for one or more threads.
    By default logging output is written to standard error.

+THREADS <number>
    Specifies the number of threads to be used and defaults to 1.

+TIMESLICE <ticks>
    Sets the number of goal-invocations after which a process yields,
    is added to the active process queue and another active process
    is scheduled.

+STATS <mask>
    Write statistics to the log file for all threads selected by the
    <mask>. The statistics are given in textual format and have the 
    following format:

    ## <THREAD> <TICKS> G <GOALS> Q <ACTIVE> S <SUSPENDED> C <CELLS>

    THREAD gives the ordinal number of the thread, starting at 1.
    TICKS is the number of internal clock ticks of the thread.
    ACTIVE is the number of active goals.  SUSPENDED is the number
    of inactive, suspended threads.  CELLS is the number of used
    cells in the heap.

+STAT_TICKS <ticks>
    Sets the number of internal clock ticks, after which statistics
    are written for a thread. The default is 100. Whenever a new
    process is scheduled, the internal clock is increased.

+HEAPSTATS <mask>
    Enable heap statistics, similar to "+STATS". The format is as
    follows:

    #$ <THREAD> <TICKS> T <TUPLES> L <LISTS> V <VARS> F <FLOATS> P <PORTS>

    TUPLES, LISTS, VARS, FLOATS and PORTS give the number of heap
    cells storing objects of the corresponding type at the time the
    statistics where written. Note that tuple arguments are stored
    in a list, so TUPLES gives the number of heap cells holding
    tuple heads.

+OCCURS_CHECK
    Enable "occurs check" to enable possibly circular variable
    unifications. This has a significant performance impact and is 
    by default disabled.

+PROFILE <filename>
    When the executable has been compiled with the "-p" option,
    write a dump with profiling information to the given file after
    execution completed and the program terminated without errors.
    The generated file will contain a breakdown of how much time was
    spent in all user processes.

+HELP
    Shows run-time option usage information.

--
    Disables any further run-time option processing.

The run-time options are also documented in the fleng(7) manual page.

FLENG and FGHC programs usually spawn many processes that run in
parallel. This implementation can utilize native threads to partition
process pools into separately executing entities to take advantage
of multi-core CPUs.


III. The FLENG Language

For a full desription of FLENG, see [1]. This implementation provides
a superset including additional computation operators for numerical
calculations. A very short description of the language is given
here. Some familiarity with Prolog is recommended to understand the
concepts used.

A FLENG program consists of a set of "process definitions", where
each definition is a set of clauses of the same name and arity:

    process_name(Argument1, ...) :- Goal1, ... .

Arguments are "matched" to the actual argument given when the process
is created. Goals are new processes to be invoked when the clause
is selected. When a process is invoked, one clause of its definition
that matches the given arguments is selected and executed, by
spawning a new process for each goal in the body, for example:

    % write each element of the given list:

    walk([]) :- true.
    walk([_|Y]) :- walk(Y).

    main :- walk([1, 2, 3]).

Each clause must have a body containing a list of goals, separated
by comma (",").  Note that all body goals are truly executed in
parallel, not in the order in which they are specified. If no clause
matches the arguments, then the process "fails", resulting in a
run-time error.

Argument variable bindings take place when clause heads are matched
and variables are distinguished by starting with an uppercase letter
or the "_" character. A variable in a clause head matches whatever
is passed as argument to clause invocation. Logic variables passed
as arguments on the other hand can only be bound by explicit
unification in the body.  Matching a non-variable argument with an
unbound variable passed by the caller, the process selection is
suspended until the variable has been bound. Here an example:

    try([Y]) :- true.

    main :- try(X), wait(X).

    wait(X) :- X = 123.

Here "try" will suspend until the unification of "X" with 123 is
performed. Once a logic variable is bound, all goals suspended on
the variable will be made active and are scheduled to be executed
at some stage, after which they may continue or suspend on other
variables. The variable named "_" is always unique, multiple
occurrences of "_" represent different anonymous variables. These
are normally used as "don't care" patterns when matching.

Once the head of a clause is fully matched, the clause "commits"
and the body goals are spawned. All other alternative clauses will
be ignored, there is no "backtracking" as in Prolog.

One specific feature of FLENG is the "!" operator. When used in the
head of a clause, a variable prefixed with "!" will suspend until
the variable is bound, regardless of whether the argument is
subsequently used or not:

    try1([X]) :- true.
    try2([!X]) :- true.

    main :- try([Z]).
    
    try(Y) :- try1(Y), try2(Y).

"try1" will match and complete, but "try2" will suspend forever,
since it waits for the first element of the given list to be bound
to some value.

In FLENG the same argument variable may not appear more than once
in a clause head.

A FLENG program terminates once there are no more active goals. If
there are still suspended goals, then a deadlock has occurred and
the program aborts with an error message.

The only built-in primitives in FLENG are "compute/{3,4}", "unify/3",
"true/0", "call/1", "=/2" and "foreign_call/{0,4}", described later
in this manual. There are further undocumented primitives which are
used for translated FGHC code.

Declarations define additional properties of the compiled module
and have the following form:

    -declaration(Argument, ...).

Currently supported declarations in FLENG are "include/1",
"initialization/1", "threads/1", "exports/1", "module/1", "foreign/1"
and "uses/1", which are described below.  Some additional declarations
exist for internal use but are not documented here. Declarations
apply to the whole source file and are processed before all other
clauses, regardless of where the declaration is located in the
source file.

FLENG is intentionally minimal to make implementing it easier. For
user programming it is recommended to use the FGHC front end described
below.


IV. The FGHC Language

"FGHC" or "Flat Guarded Horn Clauses" is another dialect of Concurrent
Prolog, descended from "GHC" which is described in [2].  It provides
clause guards, arithmetic expression evaluation and some other
syntactically convenient features. See also [3] for a general
overview over the many concurrent logic language dialects and how
they relate to each other. FGHC is "flat", meaning that only built-in
guard-expressions are allowed in the guard part of a clause, no
user defined process definitions can be used as guards.

"Strand" can be considered a slightly restricted subset of FGHC,
so code written in Strand is compiled as FGHC and can take advantage
of FGHC features like general body unfication.

An FGHC clause has the following general format:

    process_name(Argument1, ...) :- Guard1, ... | Goal1, ... .

The "Guard1, ... |" part may be omitted. If no guards and no goals
exist, the the clause may be written as
    
    process_name(Argument1, ...).

If guards exist but no goals need to be evaluated, use the following
form:

    process_name(Argument1, ...) :- Guard1, ... | true.

A guard is one of a set of predefined guard expressions that are
executed to determine if the clause commits or not. If a guard
expression fails, then another clause is selected until one clause
commits or the whole process invocation fails.

Both FLENG and FGHC support the following data types:

    signed integers             123  0xF00F  0'A
    floating point numbers      1.23
    strings (atoms)             abc  'one\ntwo'
    lists                       [1, 2, 3]  [head|tail]  "abc"
    tuples                      foo(bar, baz)  {x, y, z}
    variables                   Abc  _123  _
    ports
    modules

The atom "[]" designates the empty list.  Anonymous variables ("_")
as in Prolog are supported. Character lists enclosed in double
quotes are represented as a list of UNICODE code points. "Ports"
are identity-preserving stream containers, as described in [4],
Circular data structures are not allowed.  This is
currently only superficially checked at run-time. Tuples of the
form "{...}' may not be empty. Note that "abc(def)" is equivalent
to "{abc, def}".

Care must be taken when having multiple clauses that overlap in the
arguments they match: if multiple clauses match at the invocation
of the associated process definition, then it is unspecified which
of the candidate clauses will "fire" and be committed. You can
narrow the set of matching clauses by using guards if you want to
avoid this non-determinism:

    big(N, F) :- N > 1000 | F = yes.
    big(_, F) :- F = no.

In an invocation of "big(1001)" the second clause may match, since
matching is non-deterministic. Add another guard or "otherwise" to
remove this ambiguity:

    big(N, F) :- N > 1000 | F = yes.
    big(_, F) :- N =< 1000 | F = no.  % alternatively: "otherwise/0"

Declarations as in FLENG are supported. FGHC also allows using the
"!" annotation. The restriction that the same variable may not 
occur more than once in a clause head is lifted and equivalent to
binding a fresh variable and adding a "==/2" guard matching both
variables.

Prolog's single line ("% ...") and block ("/* ... */") comments are
supported in FGHC/Strand and FLENG.

The main differences between FGHC and Prolog can be summarized
as follows:

- FGHC is a committed-choice language and has no backtracking: once a 
  clause head matches and the guards succeed, all remaining solutions are 
  abandoned.

- All goals of a clause are executed in parallel, in an arbitrary order.

- FGHC has no general unification - clause heads and guards only match
  (and suspend if unbound variables are matched with non-variable
  arguments), variables are assigned exclusively by "=/2", "unify/3", 
  "assign/3", "is/2" and primitives that unify results with argument 
  variables.

- Matching a non-variable with an unbound variable or using it in a 
  guard other than "unknown/1" suspends the current process until the 
  variable has been bound.

For a nore in-depth description of concurrent logic languages, the
"Strand" book [5] is highly recommended as it explains the concepts
and techniques in detail and gives many examples. Strand is very
similar to FGHC, but only provides assignment instead of unification.
FGHC is similar to "KL1"[6], which was a low level language used
in Japan's Fifth Generation Computing project (FGCS)[9].

This implementation of FGHC also supports paired arguments, an extension
from KL1, that simplifies handling argument pairs. A preprocessing stage
transforms clause heads and goals of a certain form in a manner described
as follows:

(this description was taken from the "KLIC" manual)

The head and goals in body parts of a clause can have argument pairs
specified by a single variable name attached to the head or goals
by a hyphen character.  We call such a pseudo variable an "argument
pair name":

     p(X,Y)-Pair :- q(X)-Pair, s(Z)-Pair, r(Pair,Y), t(Z)-Pair.

The pseudo-variable "Pair" is an argument pair name.  Such a clause is
interpreted the same as the following clause:

     p(X,Y,P0,P) :- q(X,P0,P1), s(Z,P1,P2), r(P2,Y), t(Z,P2,P).

Occurrences of argument pair names attached to the head or goals by a
hyphen character are interpreted as a pair of two different variables
added at the end of the argument lists.  In what follows, we call the
two variables generated from an paired argument an "expanded pair".

The second of an expanded pair of a goal is the same as the first of
the expanded pair of the next goal with the same argument pair name.
In the example above, "P1" appearing as the third argument of the goal
of "q/3" also appears as the second argument of "s/3", as originally
they both have the same argument pair name "Pair".

The first of an expanded pair in the head will be the same as the
first of the expanded pair in the first goal in the clause with the same
argument pair name.  The second of an expanded pair in the head will be
the same as the second of the expanded pair in the last goal with the
same argument pair name.

In the above example, the first of the expanded pair "P0" in the
head appears again as the second argument of the first goal calling
"q/3", and "P", the second of the expanded pair in the head, appears
again as the third argument of the last goal of "t/3".

If the argument pair name appears only in the head, two variables of
the expanded pair are unified in the body.  For example, a clause:

     p(X)-Y :- q(X).

is expanded into the following.

     p(X,Y0,Y) :- Y0=Y, q(X).

An argument pair name may appear at a usual argument position rather
than being attached to the head or goals, as does the first argument
of the goal for "r/2" in the above example.  In such a case, it is
expanded to a single variable.  This variable is the same as the
second of the last expanded pair and is also the same as the first
of the next expanded pair.  Thus, in the above example, "Pair"
appearing as the first argument of "r/2" is expanded into "P2",
which is the same as the third argument of "s/3" and the second
argument of "t/3".

Arbitrarily many argument pair names can be specified for a head
or a goal.  For example, a clause such as:

     p-X-Y :- q-X, r-Y, s-Y-X.

is interpreted as follows:

     p(X0,X,Y0,Y) :- q(X0,X1), r(Y0,Y1), s(Y1,Y,X1,X).

Sometimes, specifying normal arguments after some argument pair
names is desirable.  This can be done by connecting them with a
plus ("+") character.  For example:

     p-X+Y :- q-X+35, r(Y), s+Y-X.

is interpreted as follows:

     p(X0,X,Y) :- q(X0,X1,35), r(Y), s(Y,X1,X).

Note that the expansion rules for paired arguments described above
are position sensitive for goals.  However, this does not mean that
the execution order of body goals are constrained anyhow.

Also note that the argument pair notation is no more than macro
expansion of clauses.  One predicate may have clauses some of which
written in the argument pair notation and others in the usual
notation.


V. Builtin Primitives and Support Libraries

This sections describes the available primitive operations available
in FGHC code. These primitives may be implemented as calls to the
run-time system, as calls to external C libraries, or as library
predicates written in FGHC or FLENG. Arguments with the suffix "^"
will be unified with a result value, arguments with the suffix "?"
are expected to be non-variable ("ground") values.

If a primitive is said to "signal an error", then the program will
report an error message and terminate.

Most library primitives "force" their arguments, if required, by
suspending the calling process if an argument is an unbound variable.
Notable exceptions are "compute/{3, 4}" and "unify/3".

Note that if primitives require arguments of type "string", they expect
an (interned) atom (abc, 'a string'), not a character list ("a list of
characters"). If a primitive accepts both a string or a character list
in an argument position, it specifically says so.

* Primitives by group:

    Control

        ,/2  
        call/1  call/2  call/3  apply/2  run/2
        true/0
        when/2
        &/2
        ->/2  ;/2

    Unification and assignment

        =/2
        :=/2
        assign/2  assign/3
        unify/3  unify_with_occurs_check/3
        deref/1  deref/2

    Conversion

        number_to_list/3  number_to_list/4  real_to_list/2
        string_to_real/2 
        string_to_integer/2  string_to_integer/3  
        string_to_list/3
        string_to_byte_list/3  
        list_to_string/2
        list_to_tuple/2
        list_to_number/2  list_to_number/3  list_to_real/2
        tuple_to_list/3
        utf_encode/2  utf_encode/3
        utf_decode/3

    Lists

        append/3, append/2
        member/3
        length/2

    Files

        close_file/2  close_file/3
        delete_file/1  delete_file/2
        rmdir/1  rmdir/2
        open_file/3
        file_exists/2
        file_type/2  file_size/2
        chmod/2  chmod/3

    Input/Output

        listen/2,
        write/1  write/2
        writeln/1  writeln/2
        write_file/3  write_file/4
        read_file/4

    Numeric computations

        compute/3  compute/4
        is/2

    Program environment

        command_line/1
        halt/0  halt/1
        getpid/1
        current_seconds/1
        signal/3
        clock/3  timer/3  
        cancel_timer/1  cancel_timer/2  
        restart_timer/2  restart_timer/3
        randomize/1  randomize/2
        error/1
        log/1 log/2
        environment/1
        statistics/1  heap_statistics/1

    Threads

        threads/1
        self/1
        idle_thread/1
        @/2

    Ports

        open_port/2
        send/2  send/3

    Modules

        get_module/2  all_modules/1
        current_module/1
        module_exports/2  module_name/2

    Streams

        merger/2

    Tuples

        put_arg/3  put_arg/4
        get_arg/3  get_arg/4
        make_tuple/2

    Global Variables

        get_global/2  get_global/3
        put_global/2  put_global/3

    Ordering

        compare/3

    Foreign Functions

        foreign_call/1

    Paired Arguments

        +=/2  -=/2  *=/2  /=/2
        =>/2  <=/2  <==/2

    Guards
        ==/2  =\=/2  =:=/2  \=:=/2  >/2  </2  >=/2 =</2
        @>/2  @</2  @>=/2  @=</2
        atomic/1
        data/1
        real/1  integer/1  list/1  string/1  number/1  port/1  tuple/1
        module/1
        idle/0
        known/1  unknown/1
        remote/1
        otherwise/1

    Declarations

        include/1
        initialization/1
        mode/1
        provide/2
        threads/1
        uses/1  module/1
        exports/1  machine/1
        struct/1
        foreign/1

A number of additional libraries are provided with the system that
are written mostly in FGHC and can be accessed by using the "uses"
declaration:

    fmt         Formatted output
    io          Extended I/O stream operations
    mem         Raw memory allocation and access
    proc        Invocation of sub-processes
    map         Balanced AVL trees
    sort        Sorting
    set         Lists as sets
    lex         An FGHC/FLENG lexer
    parse       Parsing of FGHC/FLENG expressions
    app         Application of goals over lists
    list        List processing operations
    scan        Basic parsers for character sequences

Consult the comments in the relevant library files for information
on how to use these modules.

The library modules "$rt", "lib" and "sys" are used internally and
provide support code for builtin operations and inter-thread
communication.

* Alphabetic list of primitives:

GOAL1, GOAL2
    Execute goals in parallel. The goals may not be variables.

MODULE:GOAL
    Invokes GOAL, which must be a tuple or string and be defined in
    and exported from the module with the given name.

GOAL@PEER
MODULE:GOAL@PEER
    Invokes the specified non-variable GOAL in the thread designated
    by PEER, which may be a variable but must be bound.  All threads
    are ordered before execution in ring and torus topologies. PEER
    specifies what neighbouring thread in a topology should receive
    the call:

        fwd  bwd        
            previous or next in the ring topology.

        north  south  east  west
            neighbours in the torus topology.

        all
            broadcast call to all threads.

    All threads are connected in the ring topology. Some threads
    may not be connected in the torus topology, depending on the
    number of threads.  Additionally PEER may be an integer thread
    number (starting at 1) addressing a specific thread in the set
    of all threads.

GUARD -> GOAL1
GUARD -> GOAL1; GOAL2
    Executes GOAL1 if the guard expression GUARD evaluates to true
    or executes GOAL2, otherwise. If GOAL2 is not given, it defaults
    to "true".

GOAL1 & GOAL2
    Execute GOAL1 in a new task (see also "call/3") and then, once 
    GOAL1 and all child processes created by GOAL1 have successfully
    executed, execute GOAL2. Note that "&/2" binds stronger than ",/2".
    Operationally, "X & Y" is equivalent to "(call(X, S), when(S, Y))".

X = Y
    Unifies X with Y by recursively comparing the values in X and Y. Unbound
    variables will be bound. In FLENG a failed unification will silently be 
    ignored. Note tha variables in X or Y may be partially bound when the
    unification fails. In FGHC a failed unification will signal an error.

X := Y
    Equivalent to "assign(Y, X, _)".

S <= M
    Equivalent to "S0 = [M|S1]" where S is a paired argument.

M => S
    Equivalent to "[M|S0] = S1" where S is a paired argument.

S <== X
    Equivalent to "S1 = X" where S is a paired argument. The previous
    value is lost and the next occurrence of S will mean X instead.

S += E
S -= E
S *= E
S /= E
    Equivalent to "S1 is S0 + E" ("-" ...)

all_modules(LIST^)
    Unifies LIST with a list of all linked modules.

append(LISTS?, LIST^)
    Concatenates all lists in LISTS and unifies the result with LIST.

append(LIST1?, LIST2?, LIST3^)
    Creates a copy of LIST1 with LIST2 appended and unifies the
    result with LIST3.

apply(GOAL?, LIST?)
    Appends the arguments in LIST to GOAL, which should be a string
    or a tuple, and invokes it with "call/1". GOAL must not be an
    invocation of a primitive operation.

assign(VAR^, VAL?)
assign(VAR^, VAL?, DONE^)
    Assigns VAL to the variable VAR, which must be unbound and
    unifies DONE with the empty list, when the assignment is
    completed. VAR must be currently unbound or contain a value
    identical to VAL or an error is signalled.

call(GOAL?)
call(GOAL?, STATUS^)
call(GOAL?, ENVIRONMENT?, STATUS^)
    Invokes the process specified by GOAL which must be a tuple
    or string. If GOAL is not a variable, then it may refer to a
    primitive operation (a suitable user-defined wrapper clause is
    synthesized by the compiler), but if it is a variable, then it 
    must refer to a user defined process.
    GOAL may refer to a module-qualified term and must be exported
    from the module in which it is defined. 

    "call/2" and "call/3" execute GOAL in a new group of processes
    called a "task". Every process created in GOAL belongs to the
    same task and once all processes in that group have terminated
    (including child tasks), unifies STATUS with the empty list.
    IF ENVIRONMENT is given, it is provided as a parameter associated
    with the task group and can be accessed by the "environment/1"
    primitive, otherwise the new task inherits the same environment
    as the current task (if any).

    Tasks may span multiple threads, a task is considered completed
    when all processes of the task and it's child tasks in all threads 
    have terminated.

cancel_timer(ID?)
cancel_timer(ID?, RESULT^)
    Cancels and removes the timer identifier by ID, previously
    created by calling "timer/3" or "clock/3" and unifies RESULT with the 
    "true" when the operation is complete. The variable associated
    with the timer is assigned the string "false" or an empty list,
    depending on whether the timer is single-shot or periodic.
    If no timer with the given ID is currently active, then this 
    operation does nothing and unifies RESULT with "false" (if given).

chdir(DIRECTORY?)
chdir(DIRECTORY?, DONE^)
    Changes the current directory to DIRECTORY, which should be a
    string or a character list. When the operation is complete,
    DONE is unified with the empty list.

chmod(FILENAME?, MODE?)
chmod(FILENAME?, MODE?, DONE^)
    Changes file permission bits of the file with the given name to
    MODE, which must be an integer and unifies DONE with the empty
    list when the operation is completed. In case of an error, DONE
    is unified with a tuple of the form "error(ERRNO)", where ERRNO
    is the UNIX error code.

clock(MS?, VAR^, ID^)
    Establishes a periodic timer and assigns an integer identifier
    to ID that can be used to cancel the timer. Every MS milliseconds
    an integer indicating the number of expirations since the last
    will be assigned to the stream in VAR.

close_file(FILE?, DONE^)
    Closes the open file with the descriptor FILE and unifies DONE
    with the empty list when the operation is completed.

command_line(LIST^)
    Unifies LIST with a list of strings holding the command line
    arguments to the currently executing program, not including the
    program name and any run-time options.

compare(X?, Y?, RESULT^)
    Unifies RESULT with -1, 0 or 1, depending on whether X is ordered
    below, equal or above Y, as compared with '@>'/2 and '@<'/2.

compute(OP?, ARG?, RESULT^)
compute(OP?, ARG1?, ARG2?, RESULT^)
    Performs a unary or binary numeric computation. OP must be a
    string and may be one of the following:

                Unary      Binary   Result
        +         -          x      Sum
        -         -          x      Difference
        *         -          x      Product
        /         -          x      Quotient
        mod       -          x      Remainder
        and       -          x      Bitwise AND
        or        -          x      Bitwise OR
        xor       -          x      Bitwise XOR
        shl       -          x      Shift bits left
        shr       -          x      Arithmetic shift bits right
        =         -          x      Equality comparison
        >         -          x      Is ARG1 numerically greater than ARG2
        <         -          x      Is ARG1 numerically less than ARG2
        min       -          x      Return lesser of the two arguments
        max       -          x      Return greater of the two arguments
        @<        -          x      Is ARG1 ordered below ARG2
        @>        -          x      Is ARG2 ordered below ARG1
        sametype  -          x      Have ARG1 an ARG2 the same type
        **        -          x      Exponentiation
        sqrt      x          -      Square root
        sin       x          -      Sine (radians)
        cos       x          -      Cosine (radians)
        tan       x          -      Tangent
        atan      x          -      Arc tangent
        abs       x          -      Absolute value
        sign      x          -      Sign (returns integer)
        rnd       x          -      Returns random integer
        real_integer_part
                  x          -      Extract integer part of float
        real_fractional_part
                  x          -      Extract fractional part of float
        integer   x          -      Convert float to integer
        real      x          -      Convert integer to float
        truncate  x          -      Truncate float
        floor     x          -      Round float to next lower integer
        round     x          -      Round float
        ceiling   x          -      Round float to next higher integer

    +, -, * and / produce real results if one of the arguments is
    a real number. "abs" returns a result of the same type as the argument.
    "**" always produces a real result. "and", "or", "xor", "rnd",
    "shl" and "shr" require integer arguments. With the exception of 
    "=", "sametype", "@>" and "@<" the arguments must be bound to numbers. 
    "@<" and "@>" implement a general ordering relation where

        vars < integers < reals < strings < lists < tuples <
          ports < modules

    Integers and reals are compared numerically, lists element by
    element, strings lexicographically, tuples by size and, if
    equal, element by element. All other objects are sorted by some
    arbitrary but stable order. Note that arguments to "compute"
    are not forced if unbound. Note that integer over- and underflow
    is not detected and will result in significant bits being
    silently truncated. "sametype" will not force unbound arguments
    (the type of the argument is considered "var" in that case).

    See "is/2" for a more convenient way to perform arithmetic 
    computations.

current_module(MODULE^)
    Assigns the module containing this expression to MODULE.

current_seconds(SECONDS^)
    Unifies SECONDS with the current UNIX timestamp in seconds 
    since 00:00, Jan. 1, 1970.

delete_file(FILENAME?)
delete_file(FILENAME?, DONE^)
    Deletes the file with the name FILENAME and unifies DONE with the
    empty list when the operation is completed. Note that no error
    is signaled if FILENAME does not exist.

deref(OBJECT?)
deref(OBJECT?, DONE^)
    Recursively derefences variables in OBJECT until the term
    is fully ground, possibly suspending. Once all variables inside
    OBJECT are bound, DONE is unified with the empty list.

environment(ENV^)
    Unifies ENV with the environment slot of the current task, or the
    empty list, if the current process does not belong to a task group.

error(MESSAGE?)
    Writes MESSAGE to standard error and terminates the program
    with exit code 1. Message may have any type and will be written
    as is, even if it contains unbound variables.

file_exists(FILENAME?, FLAG^)
    If FILENAME designates an existing file or directory, assign
    "true" to FLAG, otherwise "false". Signals an error if the
    system call fails due to other causes.

file_size(FILENAME?, BYTES^)
    Unifies BYTES with the number of bytes in the file named by the
    string or character list FILENAME. If an error occurs, BYTES is
    unified with a term of the form "error(ERRNO)" where ERRNO
    designates the error code.

file_type(FILENAME?, TYPE^)
    Unifies TYPE with the string "file", "directory", "link", "fifo"
    or "socket" depending on what type of file FILENAME refers to.
    If an error occurs, TYPE is unified with a term of the form 
    "error(ERRNO)" where ERRNO designates the error code. FILENAME may
    be a string or a character list.

foreign_call(TERM?)
    Invokes a builtin or user primitive specified by TERM. 
    TERM must be a tuple. See
    below for more information about the foreign function interface.

get_arg(INDEX?, TUPLE?, ITEM^)
get_arg(INDEX?, TUPLE?, ITEM^, DONE^)
    Unifies ITEM with the INDEXth element of TUPLE, assigning the
    empty list to DONE, if given. Indexing starts at 1. Signals an
    error if INDEX is out of range.

get_global(NAME?, VAL^)
get_global(NAME?, VAL^, DONE^)
    Retrieves the global variable named by the string NAME and unifies 
    its value with VAL. After unification of VAL is complete, and DONE
    is given, unify it with the empty list. If no global variable under 
    this name is defined, an error is signaled. Global variables are 
    thread-local.

get_module(NAME?, MODULE^)
    Assigns the module  with the given name to MODULE. If no module
    with this name is linked, an error is signalled.

getcwd(DIR^)
    Unifies DIR with a character list holding the name of the current
    directory.

getenv(NAME?, VAL^)
    Unifies VAL with a character list holding the value of the environment
    variable of the given name, which should be a string or character list.
    If no variable with that name is defined, VAL is unisifed with the
    empty list.

getpid(PID^)
    Unifies PID with the UNIX process ID of the currently executing
    program.

halt
halt(EXITCODE?)
    Terminates the program with the given exit code, which must be
    an integer and defaults to 0_.

heap_statistics(TUPLE^)
    Unifies TUPLE with a tuple of 5 elements containing the number of
    bytes currently used in the threads's heap holding variables, tuples,
    list, floats and port objects.

idle_thread(PEER^)
    Unifies PEER with the number of a random idle thread (other than
    the current). If no other thread is currently idle, PEER is unified
    with "false". Note that threads listening for input or other events 
    like signals are not considered idle.

kill(SIGNAL?, PID?)
kill(SIGNAL?, PID?, DONE^)
    Sends SIGNAL (which should be an integer or a string containing the 
    Linux/BSD uppercase signal name) to the process with the ID PID using the 
    kill(2) system call and unifies DONE with the empty list when the 
    operation is completed.

RESULT^ is EXPRESSION
    Evaluates the numerical expression and unifies RESULT with
    the result of the computation. EXPRESSION must be an arithmetic
    expression and may not contain unbound variables. Available
    operations are:

        X + Y
        X - Y
        X * Y
        X / Y           Usual arithmetic operators
        X \\ Y          Integer remainder
        +X              Identity
        -X              Negation
        \X              Bitwise NOT
        sqrt(X)
        integer(X)      Truncate and convert to integer
        real(X)        Convert integer to float
        X /\ Y          Bitwise AND
        X \/ Y          Bitwise OR
        X >< Y          Bitwise XOR
        X << Y          
        X >> Y          Shift X by Y
        X ** Y          Exponentiation of X by Y
        rnd             Pseudo random float betwwen 0 and 1
        rnd(X)          Random integer between 0 and X-1
        floor(X)      
        ceiling(X)
        round(X)        Rounding operations
        sin(X)
        cos(X)
        tan(X)
        atan(X)         Trigonometry
        log(X)          Natural logarithm
        exp(X)          Exponential value
        abs(X)          Absolute value
        sign(X)         Sign
        real_integer_part(X)   
        real_fractional_part(X)
                        Deconstruct floating-point value
        max(X, Y)
        min(X, Y)       Return greater or lesser argument

    Random numbers returned by "rnd/0" are uniformly distributed,
    "rnd/1" uses a slightly faster method and may not be uniformly
    dsitributed.
    Note that variables holding valid arithmetic expressions (as
    in ISO Prolog) are not supported.  Signals an error if any
    argument is not numeric.

length(OBJECT?, LEN^)
    Unifies LEN with the length of OBJECT, which may be a string,
    a list or a tuple.

list_to_number(LIST?, NUMBER^)
list_to_number(LIST?, BASE?, NUMBER^)
    Unifies NUMBER with the number consisting of the characters
    in LIST, which must specify a valid integer or floating point 
    number. If LIST designates an integer, BASE determines in what
    numeric base the conversion should occur.

list_to_real(LIST?, REAL^)
    Similar to "list_to_number/2", but implicitly converts the
    result into a floating-point number.

list_to_string(LIST?, STRING^)
    Unifies STRING with the string holding the UNICODE code points
    in LIST.

list_to_tuple(LIST?, TUPLE^)
    Unifies TUPLE with the string holding the elements of LIST.
    If LIST is the empty list, TUPLE will be unified with the empty
    list as well (there are no empty tuples).

listen(FILE?, VAR^)
    Registers the file descriptor FILE with the internal polling
    loop and unifies VAR with the empty list once data can be read 
    from the file. To listen again, invoke "listen" again for
    the same file. If an error occurs, then VAR will be unified with
    a tuple of the form "error(ERRNO)", where ERRNO is the UNIX
    error code.

log(MESSAGE?)
log(MESSAGE?, DONE^)
    Dereferences MESSAGE fully and writes it into the log file.
    After the message is written, DONE is unified with the empty list.

make_tuple(LENGTH?, TUPLE^)
    Unifies TUPLE with a fresh tuple of the specified length, the
    resulting tuple is populated with unbound variables. Signals
    an error if LENGTH is not between 0 and 127. Creating a tuple
    of length 0 will unify TUPLE with the empty list.

member(VALUE?, LIST?, BOOL^)
    Unifies BOOL with the string "true" or "false", depending on
    whether LUST contains a toplevel element that matches VALUE.

merger(INSTREAM?, OUTSTREAM^)
    Takes elements from INSTREAM and writes them to OUTSTREAM.
    Element of the form "merge(STREAM?)" in INSTREAM result in 
    merging the elements from STREAM into OUTSTREAM. Items are added 
    to the output stream in an arbitrary order, but retain the
    order from the respectively merged streams. Merged streams
    may again receive "merge(STREAM)" messages. Once all streams
    are terminated with the empty list, OUTSTREAM is terminated
    as well.

module_exports(MODULE?, LIST^)
    Unifies LIST with the list of exported process definitions 
    contained in MODULE. Each element of the list will be a tuple of 
    the form '/'(NAME, ARITY).

module_name(MODULE?, NAME^)
    Assigns astring holding the name of MODULE to NAME.

number_to_list(NUMBER?, LIST^, TAIL?)
number_to_list(NUMBER?, BASE?, LIST^, TAIL?)
    Converts the integer or real NUMBER into a list of character
    codes terminated by TAIL and unifies it with LIST.

open_file(NAME?, MODE?, FILE^)
    Creates or opens a file with the name NAME in the given MODE,
    which may be one of the strings (not character lists!) "r" (read),
    "w"(write) or "a" (append). The file descriptor will be unified
    with FILE.  If the system call fails, FILE will be unified with
    a tuple of the form "error(ERRNO)", where ERRNO is the UNIX
    error code.

open_port(PORT^, LIST^)
    Creates a "port" object and unifies it with PORT. LIST is
    unified with a "stream" receiving objects send to PORT using
    the "send" primitive. When the port is not referenced anymore,
    the stream is closed by assigning the empty list to its tail.

put_arg(INDEX?, TUPLE?, ITEM?)
put_arg(INDEX?, TUPLE?, ITEM?, DONE^)
    Unifies the INDEXth element of TUPLE with ITEM, assigning the
    empty list to DONE, if given. Indexing starts at 1. Signals an
    error if INDEX is out of range.

put_global(NAME?, VAL^)
put_global(NAME?, VAL^, DONE^)
    Assigns VAL to the global variable named by the string NAME and 
    unifies DONE with the empty list when the assignment is completed.
    Global variables are thread-local.

randomize(SEED?)
randomize(SEED?, DONE^)
    Initializes the internal pseudo random number generator. SEED
    should be a string or a byte list. The buffer holding the random
    state has a size of 16 machine words. If the byte sequence given
    by SEED has a smaller size, then initialization "wraps around"
    to the start of SEED again. Once the random number generator
    has been initialized, DONE is unified with the empty list.
    On startup the random number generator is seeded with the
    system time.

readlink(FILENAME?, VAL^)
    Unifies VAL with a character list holding the contents of the
    symbolic link FILENAME. If an error occurs, VAL is
    unified with a term of the form "error(ERRNO)" where ERRNO
    designates the error code.

read_file(FILE?, COUNT?, LIST^, TAIL?)
    Reads COUNT bytes from the file designated by the file descriptor
    FILE and unifies LIST with the read data, terminated by TAIL.
    If an error occurs, then LIST will be unified with a tuple of the
    form "error(ERRNO)", where ERRNO is the UNIX error code.

real_to_list(REAL?, LIST^)
    Converts the floating-point number REAL to a list of character codes.

restart_timer(ID?, MS?)
restart_timer(ID?, MS?, RESULT^)
    Modifies the timeout for the timer identified by ID and previously
    created by calling "timer/3" or "clock/3" and unifies RESULT with 
    "true" when the operation is complete. MS specifies the new
    timeout (possibly periodic when ID designates a periodic timer).
    If no timer with the given ID is currently active, then this 
    operation does nothing and unifies RESULT with "false" (if given).

rmdir(FILENAME?)
rmdir(FILENAME?, DONE^)
    Deletes the directory with the name FILENAME and unifies DONE with the
    empty list when the operation is completed. Note that no error
    is signaled if FILENAME does not exist. In case the operation
    fails DONE is unified with a tuple of the form "error(ERRNO)",
    where ERRNO is the UNIX error code.

run(MODULE?, TERM?)
    Invokes TERM similar to "call/1" in the module represented by MODULE,
    which may be a module object or a name referring to a linked
    module.

self(ID^)
    Unifies ID with the thread number of the thread that is executing
    the current clause.

send(PORT?, OBJECT?)
send(PORT?, OBJECT?, DONE^)
    Sends OBJECT (which may be any data objecv whatsoever) to
    PORT and unifies DONE with the empty list, when given.

signal(SIGNAL?, VAR^)
signal(SIGNAL?, VAR^, DONE^)
    Installs a signal handler for the signal with the name given
    by the string SIGNAL, which should be an integer or a valid uppercase 
    Linux/BSD signal name. If the signal is raised, or was raised since the
    program started, the number of times the signal was raised since
    is added as an integer to the stream in VAR. 
    Handling of the signal can not be disabled, once the signal
    handler was installed.

statistics(TUPLE^)
    Unifies TUPLE with a tuple of 4 elements containing the number of
    goals, active goals, suspended goals and used heap-cells.

string_to_real(STRING?, REAL^)
    Converts the atom STRING to a floating-point number.  If STRING
    can not be converted, then an error is signaled.

string_to_integer(STRING?, INTEGER^)
string_to_integer(STRING?, BASE?, INTEGER^)
    Converts the atom STRING to an integer, interpreting the
    characters in STRING in BASE. BASE defaults to 10. If STRING
    can not be converted, then an error is signaled.

string_to_byte_list(STRING?, LIST^, TAIL?)
    Converts STRING to a list of bytes, terminated by TAIL.

string_to_list(STRING?, LIST^, TAIL?)
    Converts STRING to a list of UNICODE code points, terminated by
    TAIL.

threads(NUMBER^)
    Unifies NUMBER with the number of threads, as given to the
    "+THREADS" run-time option on startup.

timer(MS?, VAR^, ID^)
    Establishes a single-shot timer that unifies VAR with the empty
    list after MS milliseconds have passed. ID is unified immediately
    with an integer identifying this timer and can be used to cancel
    the timer before it has expired.

true
    Does nothing.

tuple_to_list(TUPLE?, LIST^, TAIL?)
    Unifies LIST with the elements of TUPLE, terminated by TAIL.

unify(X?, Y?, RESULT^)
    Unifies X with Y and finally unifies RESULT with the string "true" or 
    "false", depending on whether the unification succeeded or
    failed. Variables bound during the unification will be restored to 
    their unbound state if the full unification should fail.
    Note that this primitive receives the result variable in the third
    argument position, which differs from the description given in [1].
    Also note that "remote" variable bindings in other threads are
    not restored on failure and still trigger inter-thread messages
    that negotiate the final value.

unify_with_occurs_check(X?, Y?, RESULT^)
    Similar to "unify/3", but fails in case a binding would make a variable
    directly or indirectly refer to itself. This primitive always performs
    the check, regardless of the "+OCCURS_CHECK" runtime option.

utf_decode(LIST?, OUTLIST^)
utf_decode(LIST?, CHAR^, REST^)
    Converts bytes in LIST to UNICODE code points. The former
    primitive writes characters into the stream OUTLIST until
    LIST is exhausted and closes OUTLIST by unifying it with the
    empty list. The latter primitive converts a single character
    and unifies REST with the remaining elements of LIST.

utf_encode(CHAR?, LIST^, TAIL?)
utf_encode(INLIST?, OUTLIST^)
    Convert UNICODE code points into a stream of bytes. The first
    primitive takes a character code and unifies LIST with the
    list of bytes required to encode CHAR, terminated by TAIL.
    The second primitive receives a stream of code points and
    produces a stream of bytes until the end of INLIST is reached,"
    after which OUTLIST is unified with the empty list.

when(VAR?, GOAL)
    Executes GOAL, which must not be an unbounded variable, once
    VAR is bound.

write(OBJECT?)
write(OBJECT?, DONE^)
    Fully dereferences OBJECT and writes it to standard output.
    After writing, DONE is unified with the empty list, if given.

write_file(FILE?, DATA?, REST^)
write_file(FILE?, DATA?, COUNT?, REST^)
    Writes COUNT bytes of DATA to the file designated by the file
    descriptor FILE and unifies REST with the empty list or any
    yet unwritten data. DATA may be a string or a byte list.
    If COUNT is not given, writes DATA completely. When an error
    occurs, REST will be unified with a tuple of the form
    "error(ERRNO)", where ERRNO is the UNIX error code.

writeln(OBJECT?)
writeln(OBJECT?, DONE^)
    Fully dereferences OBJECT and writes it to standard output,
    followed by a newline character. After writing, DONE is unified
    with the empty list, if given.

* Alphabetical list of guard expressions:

X == Y
    Succeeds if X matches Y. Note that matching never binds logic
    variables. If an argument variable in a clause head occurs
    several times, then subsequent occurrences imply an argument
    match equivalent to using "==/2", e.g.

    foo(X, [X]) :- ...

    is the same as

    foo(X, [Y]) :- X == Y | ...

X =\= Y
    Succeeds if X does not match Y.

X =:= Y
    Succeeds if X is numerically the same as Y, X and Y may be 
    numerical expressions as in "is/2".

X \=:= Y
    Succeeds if X is numerically different to Y. X and Y may be 
    numerical expressions.

X > Y
    Succeeds if X is numerically greater than Y. X and Y may be 
    numerical expressions.

X < Y
    Succeeds if X is numerically less than Y. X and Y may be 
    numerical expressions.

X >= Y
    Succeeds if X is numerically greater than or equal to Y. X 
    and Y may be numerical expressions.

X =< Y
    Succeeds if X is numerically less than or equal to to Y. X 
    and Y may be numerical expressions.

X @> Y
    Succeeds if X is ordered above Y.

X @< Y
    Succeeds if X is ordered below Y

X @>= Y
    Succeeds if X is ordered above or equal to Y.

X @=< Y
    Succeeds if X is ordered below or equal to Y.

atomic(X)
    Succeeds if X is a number or a string.

data(X)
    Suspends if X is an unbound variable. This is identical to
    qualifying a head variable with "!".

idle
    Suspends the clause until the current thread us "idle", that is,
    when no active processes are scheduled for execution. Once idle,
    the process will continue and subsequent matching of an "idle"
    guard will wait for the next idle cycle. Note that threads listening
    for input or other events like signals are not considered idle.

integer(X)
    Succeeds if X is an integer.

known(X)
    Succeeds if X is a non-variable object or a bound variable, the 
    guard does not suspend in the case that X is bound.

list(X)
    Succeeds if X is a non-empty list.

module(X)
    Succeeds if X is a module object.

number(X)
    Succeeds if X is an integer or a floating point number.

otherwise
    Always succeeds. A clause with this guard will only be matched
    if all textually previous clauses of the same process definition
    failed to match.

port(X)
    Succeeds if X is a port object,

real(X)
    Succeeds if X is a floating point number.

remote(X)
    Succeeds if X is a variable or port object located in a different
    thread than the current one.

string(X)
    Succeeds if X is a string. Note that this includes the empty
    list ("[]").

tuple(X)
    Succeeds if X is a tuple.

unknown(X)
    Succeeds if X is an unbound variable, the guard does not
    suspend in that case.

* Alphabetical list of declarations:

foreign(SPECLIST)
    Creates stubs and wrappers for external native code. SPECLIST should
    be a list of foreign-call specifications or strings and generates
    FLENG stubs that call generated C wrapper code which is produced in
    a file named "<module>.c", where "<module>" is the name of the currently
    compiled module. If no module is declared, the file will be named
    "foreign.c". See below for a description of the interpretation of
    the specification format.

exports(EXPORTLIST)
    EXPORTLIST should be a list of "<Name>/<Arity>" specifications of
    predicates that should be visible to external modules. If this
    declaration is not given, then by default all predicates are exported.

include(FILENAME)
    Includes the contents of FILENAME at the current toplevel position
    in the compiled file.

initialization(PROCESSLIST)
    Declares that on startup, the processes given will be spawned.
    PROCESSLIST should be a string or a list of strings naming predicates
    with zero arity, which must be defined, but not necessarily exported.

machine(TOPOLOGY)
    Provided for Strand compatibility. Only "ring" and "torus"
    topologies are allowed. This declaration has no effect.

mode(CLAUSE)
    Declares the predicate defined by CLAUSE to have a mode. CLAUSE should
    specify a predicate term "<name>(<mode>, ...)", where "<mode>" is
    either the symbol "?" or "^". The compiler will transform arguments
    to the predicate marked as "^" into an explicit output-argument
    unification, e.g.

        -mode(wheels(?, ^)).
        wheels(car, 4).

    is equivalent to

        wheels(car, X) :- X = 4.

    Output arguments (marked as "^") may not be used in guards.

module(NAME)
    Declares the name of the current module, unless the file was 
    compiled with the "-m" command line option. If not given and
    no module name was specified during the invocation of the
    compiler, the module name defaults to the empty ("") module,
    which is the program's main module.

provide(SPECIFICATION, PROVIDER)
    Creates a dispatching predicate that invokes the given provider with
    arguments prepared according to SPECIFICATION, which should be a
    predicate term with the symbols "?" or "^" as arguments. 
    This is best explained by an example:

        -provide(find_address(?, ^), db_lookup('addressbook')).

    Any invocation of "find_address/2" will be passed to "db_lookup/2",
    with the prepared argument list passed as an additional argument:

        find_address('Person #1', Addr)

        results in

        db_lookup('addressbook', ['Person #1', Addr])

    Arguments of "?" in SPECIFICATION will be fully dereferenced 
    before the call to the provider. "^" should be used for "output" 
    arguments. PROVIDER can be an optionally module-prefixed string or
    tuple, or a "foreign_call" invocation.

    This declaration is mostly useful for delegating calls to external
    database facilities and/or foreign code.

struct(TUPLE)
    Generates code to easily extract and modify tuple components. TUPLE
    should be a named tuple of length > 1. A struct declaration of the
    form

        -struct(point(x, y)).

    produces code similar to (but slightly more efficient than):

        point_x(point(X, _), Y) :- Y = X.
        point_y(point(_, X), Y) :- Y = X.
        point_x(X, point(_, B), Y) :- Y = point(X, B).
        point_y(X, point(A, _), Y) :- Y = point(A, X).

    Note that the update predicates take the new value as the first 
    argument.

threads(NUMBER)
    Declares that NUMBER threads should be initialized and prepared
    for execution. Execution always commences in thread 1, additional
    threads start executing when processes are invoked using the
    "@" notation. This declaration should only be used in the main
    module (named ''), if more than one module contains this declaration,
    an error is signaled.

uses(MODULELIST)
    Declares that the modules should be loaded and process
    definitions be made available for use using the "MODULE:GOAL"
    notation. MODULELIST may be a string or a list of strings.
    In FGHC, declarations for modules called directly using the 
    "MODULE:GOAL" notation are added automatically and so not
    required.

* Precedence and associativity of infix operators:

The precedence and associativity of numerical operators follows the
usual ISO Prolog syntax:

        Operator        Associativity

        + - \           fy              Highest precedence

        **              xfx

        * / \\ << >>    yfx

        + - /\ \/ ><    yfx

        :               xfy

        == =\= =:=
        \=:= @< @> @=<
        @>= > <
        >= =< @         
        <= => <== 
        += -= *= /=     xfx

        =  :=  is       xfx

        &               xfy

        ,               xfy

        ->              xfy
    
        ;               xfy

        |               xfy

        :-              xfx             Lowest precedence


VI. Programming Tips

* Sequencing process execution

If processes must run sequentially, there are three methods
for ensuring non-parallel execution, with different run-time
costs and partially different semantics. The cheapest method
is to assign a value to a dedicated unbound variable and 
force the argument in a clause head to be bound:

    seq :- first(A), second(A).
    first(A) :- ..., A = [].        % "[]" used by convention
    second(A) :- data(A) | ... .    % alternatively: "second(!_)"

The second option is to use "when/2":

    seq :- first(A), when(A, second).
    first(A) :- ..., A = [].
    second :- ... .

"when/2" is basically equivalent to the first method, but
creates a compiler-generated intermediate predicate that
performs the dereferencing (and possible suspension) of the
assigned variable.

The third method is to use "&/2", which runs the first goal
as a child task and invokes the second goal when the task and
all processes spawned by the task have completed:

    seq :- first & second.

Note that if "first" starts a recursive process, then "second"
will not be executed until the process finishes. The example
is mostly equivalent to the following:

    seq :- call(first, A), when(A, second).

Task-creation and maintenance will have a slight run-time cost,
so performance critical code may try to avoid using tasks in
this situation.

* Module prefixes in uses of "call" and "apply"

Dynamic calls assume the target predicates belongs to the
module that contains the "call" or "apply" form, unless the
invoked form is already prefixed with a module name using the
":/2" operator. Indirect calls and applications, which occur
for example in library code (notably in the "app" library) 
do not have information about the calling module, so this
cases the module defaults to "" (the empty module name)
which is the main application module.

* Runaway stream producers

When processes that produce and consume streams run at different
speeds, it may happen that the consumer is not able to process
elements from the stream fast enough to avoid the build up of an
ever larger number of input elements. As an example, consider the
following code:

    io:read_lines(File, Lines), consume(Lines).

If "consume" runs slower than the library code that reads in the
stream of lines, a large file will create a stream holding most or
all of the contents of the file, while the consumer processes only
a small part of the data at a time, possibly filling up the available
heap space. In this example, "io:read_lines_bounded" can be used,
but the problem exists in every situation where data is produced
quicker than it can be consumed. In such situations the producer
must be slowed down artifically, by using bounded buffers (where
the consumer explicitly provides elements to the producer to be
filled) or by using some other method of signalling to the producer
that new data is required.

Another situation exists when processes are created at a high rate,
without requiring synchronization:

    loop :- process_user_input, loop.

This will quickly exhaust the available goal space by spawning
processes excessively, since the call to "loop/0" can proceed
immediately, even though the intent is to read and process input
from the user.  The remedy is to explicitly wait for data to be
read and processed fully before starting the next iteration of the
loop, for example by using "when/2":

    loop :- process_user_input(Done), when(Done, loop).

where "process_user_input/1" unifies "Done" with some value when
it is ready for new input. Alternatively, you can use "&/2" and
run the processing in a separate task, if possible background 
processes spawned in reaction to the input are ensured to be
completed:

    loop :- process_user_input & loop.

* Overlapping matches and "otherwise"

The order in which goal arguments are matched with clause heads is
not specified and may not follow strict left to right order or the
order of clauses in the source code. Heads of clause definitions
that overlap may cause unexpected behaviour. For example:

    start :- perform_work(A), foo(A).

    foo([A]) :- ... .
    foo(A) :- ... .

Both clauses may match if "foo" is called with a one-element list,
as the order of matching and unification is not defined. It is
advisable to use the "otherwise/0" guard to identify fallback clauses
that should be matched if all previous clauses are guaranteed to
be failing.  The FGHC compiler will detect overlapping clause heads
in some cases (but not all) and issue a warning.

Sometimes this overlapping is desired, for example when 
simultaneously consuming more than one stream:

    merge([X|S], S2) :- ...
    merge(S, [Y|S2]) :- ...

Here we want to suspend on either stream and are sure that at least
one stream will be instantiated. Still, an otherwise clause will
not hurt and may also catch unexpected cases.

* Variable matching in guards

Unbound variables in guards will cause a process to suspend. This may
be unintuitive for the user as unbound variables in clause heads do not
cause a suspension:

    foo(A, B) :- B == x(_) | ...

In the example, "A" will not cause a suspension, even if the argument
passed to "foo/2" is unbound. But the match of "B" with will suspend
on "B" (if it is unbound) _and_ will also suspend forever, because
it will try to dereference the anonymous variable ("_"). This can
be considered a bug.

* Interprocess comunication ("detached ports")

Message exchange between threads normally takes place via shared
memory "message ports" where threads store and retrieve message 
data passed between different execution contexts. These ports
can also be "detached" by placing them into files on disk that
allow shared access by different processes. The "sys" library
provides operations to detach a message port and to attach to
a port already detached by a different process. Messages can
only be sent to a detached port and must not contain unbound
variables or references to "live" data that can not be meaningfully
deserialized by the receiving process, like port objects. To
perform bidirectional communication, both processes have to detach
message ports and need to know the filename of respective peer's
port file.

Here is a simple example:

    % a
    -initialization(main).
    main :- sys:detach_message_port('/tmp/a', _).
    forwarded(Msg) :- fmt:format('a received: ~q\n', [Msg]).

    % b
    -initialization(main).
    main :-
        sys:attach('/tmp/a', _, Addr),
        command_line(Args),
        sys:transmit(Addr, Args, _).

    $ fleng a.ghc -o a.out
    $ fleng b.ghc -o b.out
    $ b.out hello world
    a received: [hello, world]

Only the thread calling "sys:detach_message_port/2" will have its
port detached, all other threads still use a process-local message
port, but communication between threads with detached and undetached
ports still works as normal.

* Networking 

FLENG has no built-in networking facilities. It is recommended
to run tools like socat(1) [7] as subprocesses, using the "proc"
library module.

* Cleaning up resources once they are no longer needed

Especially when interfacing to foreign code it may be necessary
to control when resources are being freed. A particularly useful
idiom is to use a "port" object, which closes the associated
stream once the port is not referenced anymore by a process:

    create_resource(P) :-
        open_port(P, S), 
        <create resource R>
        spin(S, R).

    spin([], R) :- <release resource R>.

Since ports are also useful as a message or command interface and 
ensure serialization of requests, they are generally useful to
implement all accesses to specific resources.


VII. Debugging

To analyse run-time errors, execution can be logged to standard error
or a dedicated file using the "+LOG" run-time option. If a FLENG or
FGHC file is compiled using the "-d" option, each entry into a
clause is written to the log-file. Assignment, suspension and
resuming is logged for modules compiled with the "-d" option.

Logging can be enabled for specific threads by using a suitable
bit-mask specifying the threads that should be logged. The log-file
is never deleted and new information is appended at the end, so you
can use "tail -f" to follow the log over mulitple runs. The "+LOGX"
option only logs explicit calls to "log/1".

Additionally, information about the overall status of the program
is logged. If the "+STATS" or "+HEAPSTATS" run time options are
given, statistics about memory use and process load are logged and
can be subsequently filtered and analyzed using the "plot" utility
included in the distribution which uses gnuplot(1) to show a graph
of the collected statistics data like the number of active and
suspended goals and an overall breakdown of heap usage. Note that
logging has a severe performance impact due to file-system access
and thread locking.

Configuring the build with "--debug" adds debugging information
to the C run time library and enables additional events to be
logged.

Code execution can be profiled by using the built-in statistical
profiler. Compiling your programs and library modules with the "-p"
option will instrument the code to provide profiling information.
When you run a thus instrumented executable with the 
"+PROFILE <filename>" run-time option, then on successful execution
timing information is written to the given file in textual format.

"plot" takes a log file and extracts either heap statistics (when
the "-heap" option is given) or one or more of "axis" names that
should be plotted in a graph. Only the latest run will be plotted
if the log file holds logging data from multiple runs.


VIII. Data Representation and Interfacing to C Code

Memory for all data objects is allocated from the "heap", which
holds fixed size "cells". All data is made up from cells and each
thread has its own private heap, data is (usually) never shared
between threads. Unused memory is reclaimed using a reference
counting scheme, where every store of a cell pointer increases the
reference count and any release of a cell reduces the count.  Once
the count reaches zero, the cell is reclaimed and stored in the
"freelist" from which new allocations take cells for further use.

Cells have 3 fields: a "tag" and reference count cell, a head and
a tail. The tag specifies what type of object the cell is representing,
the head and tail point to other objects or contain integers.

A datum is either a cell-pointer (of type "FL_CELL *), an integer
of machine word size or a pointer to a string. Integers and strings
are distinguished from pointers by having the lowest and next to
lowest bit set, respectively, which means the cells are always
located at a word size boundary. Integers are representable in the
range of 63 (on 64 bit systems) or 31 bits (on 32 bit machines).

The base type on the C level for all objects is "FL_VAL".  Cells
should never be modified destructively.

Strings are "interned" and unique, a string with a given name exists
only once in the entire process.

Depending on type, the fields of a cell have various meanings:

                    Head            Tail
    List            List head       List tail
    Real            IEEE double     Unused*
    Variable        Value+          Suspensions
    Tuple           Head/name       Arguments (list)
    Port            Stream|source   Unused
    Module          Internal^       Unused
    Ref             Source%         Unused

    *: on 32 bit systems the head + tail fields contain the double
    +: points to the variable if unbound
    ^: internal pointer to module structure, with lowest bit set
    %: contains a pointer to a variable in another thread, with the
       lowest bit set

A "ref" is a variable-like object referencing a variable in another
thread.

To call native code from FGHC or FLENG you can use the "foreign_call"
form, which generates a call to an external function using the C
ABI:

    foreign_call(my_func(Argument, ...))

will invoke an externally visible C function with the following
prototype:

    void my_func_<N>(FL_TCB *tcb, FL_VAL, ...))

"<N>" is the number of arguments passed to the foreign function,
at most 4 arguments can be passed. The "tcb" argument holds a pointer
to a "thread control block" designating the thread context in which
this foreign function is invoked.

Normally, user code should not manipulate the reference counts of
arguments or results, this is automatically handled by the compiler.
Cell-pointers stored in external memory must have their reference
count increased or may be invalidated when their reference count
is decremented to zero in other code using the value.

Note that while your foreign code executes, the runtime can not 
process other processes, the thread is effectively blocked until
the foreign code body has finished and returns to the caller. 
Therefore it is important to minimize the execution time and perform
polling of I/O and other resources with the means provided by the
FLENG runtime system ("listen/2", timers and clocks, for example).
Also, if foreign code requires data passed in arguments to be
dereferenced (possibly by waiting until variables are bound), this
should be done on the FGHC/FLENG side, see "deref/2".

To simplify the creation of wrapper code, the "foreign/1" declaration
can be used, allowing the automatic generation of FLENG stub 
predicates and associated C wrapper code. "foreign/1" receives a
list of specifications (or a single specification) defining the
name and argument and result types that a foreign function accepts:

    -foreign('#include <math.h>').
    -foreign([modf(real, -real, -real)]).
    -initialization(main).
    main :- modf(1.23, I, F), writeln([I, F]).

A specification can either be a tuple describing a foreign function,
a foreign struct specification, a foreign constant definition or
an atom holding C code that is inserted verbatim into the generated
wrapper code. A function specification gives the name and argument
types that the function expects, where results and "output" arguments
are preceded by a "-". The meaning of the types and their interpretation
follow these rules:

    1. If an argument list ends with an output ("-...") argument, then
       this argument is taken as the type of the function result.
    2. If no output arguments are given, or if the final type is "-void",
       then the function is expected to have no return type.
    3. Output arguments are passed as pointers to the foreign function
       (with the exception of the final return type).
    4. Arguments of type "string", "list" and "tuple" are completely
       dereferenced before they are passed to the foreign function.
    5. All arguments, except output arguments and arguments of type "any"
       are "forced", execution will block until they are bound.
    6. If no result type is given and the function has no output arguments,
       an implicit final argument is added and unified with the empty
       list when the function returns.

The wrapper predicate will have the same name as the name given in the
function specification, unless the specification has the form

    <localname>=<foreignname>(...)

In this case the FLENG predicate is named "<localname>".

Specification types are mapped to C types according to the following
table:

    Type            C

    integer         int
    short           short
    long            long
    char            char
    real            double      also accepts integer as argument
    string          char *      
    charlist        char *      also accepts string as argument
    tuple           FL_VAL
    list            FL_VAL
    any             FL_VAL
    pointer         void *
    pointer(T)      T *
    void            -           only allowed as return type

Foreign structs are defined like thisL

    -foreign(struct(NAME(SLOT1:TYPE1, ...))).

An example should make this clear:

    -foreign(struct(vector(-x:real, -y:real, -z:real, moved:integer)).

The "-..." marks read-only slots, so the following predicates will be
generated:

    vector_x(POINTER?, VALUE^)
    vector_y(POINTER?, VALUE^)
    vector_z(POINTER?, VALUE^)
    vector_moved(POINTER?, FLAG?, DONE^)
    vector_moved(POINTER?, FLAG^)

Setter predicates take a third argument that is unified with the empty
list when the operation is complete.

The "<localname>=<foreignname>(...)" syntax is allowed here as well to
allow using a specific name prefix for the stub predicates.

Finally, foreign constant are defined as follows:

    -foreign(const(eof = 'EOF':integer)).

This defines a predicate "eof(EOF^)" that assigns the C EOF code to
the result variable "EOF". The "<Name> =" prefix can be omitted if
the native name shall be used.


IX. Bugs and Limitations

* System limits:

    Maximal number of threads:            64 (32 on 32-bit platforms)
    Maximal number of local variables:              64
    Maximal size of message sent to other threads:  4096 bytes
    Number of uninterrupted goal calls:             10

    These settings can be changed using run time options:

    Default heap size per thread:                   1000000 bytes
    Default timeslice:                              10
    Maximal number of active or suspended goals:    10000
    Number of ticks between logging of statistics:  50

* Known bugs and shortcomings:

- The generated code is should be more compact and more efficient.

- There is currently not mechanism for catching errors, failed
  run-time errors result in a termination of the program.

- Some attempt is made to prohibit the creation of circular data
  structures, but not all edge cases are likely to be addressed.


X. Code Repository

A git[8] repository hosting the sources can be found here:

    https://gitlab.com/b2495/fleng/


XI. Further Reading

[1] "FLENG Prolog - The Language which turns Supercomputers into 
    Parallel Prolog Machines"
    Martin Nilsson and Hidehiko Tanaka 

[2] "Guarded Horn Clauses"
    PhD Thesis, Kazunori Ueda

[3] "The Deevolution of Concurrent Logic Programming Languages"
    Evan Tick

[4] "Ports of Objects in Concurrent Logic Languages"
    https://people.kth.se/~johanmon/papers/port.pdf

[5] "Strand: New Concepts for Parallel Programming",
    Ian Foster and Stephen Taylor, Prentice Hall, 1990

[6] "Design of the Kernel Language for the Parallel Inference Machine", 
    U. Kazunori et al., 1990

[7] http://www.dest-unreach.org/socat/

[8] https://git-scm.com

[9] https://en.wikipedia.org/wiki/Fifth_generation_computer


XII. License

This software was written by Felix L. Winkelmann and has been released 
into the public domain. Some parts of the code are authored by other 
people, see the file "LICENSE" in the source distribution for more 
information.


XIII. Contact Information

In case you need help, have suggestions or ideas, please don't 
hesitate to contact the author at

    felix AT call-with-current-continuation DOT org