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


    User Manual


    Version: 20


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 front ends for "Flat Guarded Horn
Clauses" (FGHC)[2], "Strand"[5] and "PCN"[10] are provided, which are
higher level and more convenient languages.


II. Usage

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

    fleng [OPTION ...] SOURCEFILE

The script takes FLENG, Strand, PCN or FGHC source files and generates
assembler, binary object files or executables. Enter

    man fleng

or

    flengdoc fleng

to read about the available compiler options.

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.

The file extension of the source file determines as in what language the
source code is to be written, it should be ".ghc" or ".st" for FGHC and
Strand, or ".pcn" for PCN, respectively. Alternatively, use the "-l"
option to specify explicitly in what language the code is written in.

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. Separate
compilation is straightforward by compiling library modules into
object files that can then be linked with the main module.

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

    man 7 fleng

or

    flengdoc options

to obtain more information about the available run-time options.

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.

Enter

    flengdoc

to explore the available documentation interactively, or

    flengdoc '<name>'

to see documentation for a particular primitive, library module or
syntactic element.

After you have installed the system you can try it out. If you
do not want to install it yet, just build it and set the FLENG_PREFIX
environment variable:

    $ export FLENG_PREFIX=.                                 [FGHC]
    $ cat examples/hello.ghc
    % the canonical first program
    -initialization(main).
    main :- writeln('hello, world.').
    $ ./fleng examples/hello.ghc
    $ ./a.out
    hello, world.

Finally, a tool for building more complex programs and libraries
is provided with "flengmake". Enter

	man flengmake

or

	flengdoc flengmake

for more information.


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 helpful to understand the
syntax and concepts used, but Prolog has quite a different evaluation
model and one is not required to be proficient in it to learn
FLENG, which is in a sense considerably easier to understand.

If you prefer a more traditional syntax, skip to section "V. The PCN
Language" below, which describes "PCN" (Program Composition Notation),
which has more similarity with C-like languages and may be more
accessible for users that do not have a Prolog background.

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:                 [FGHC]

    -initialization(main).  % start execution at "main" goal

    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:

    -initialization(main).                                  [FGHC]

    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:

    -initialization(main).                                  [FGHC]

    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/1", 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, ...).                            [FGHC]

Currently supported declarations in FLENG are "include/1",
"initialization/1", "arguments/1", "exports/1", "module/1", "foreign/1"
and "uses/1", which are described in the "LIBRARY" file and via
flengdoc(1).  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 it easy to implement and
should be considered a suitable target language for compilers that
translate higher-level languages. For user programming it is
recommended to use the FGHC or PCN front ends 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 output 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 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. Source code
may contain arbitrary UNICODE characters as long as the basic
syntactic requirements are fulfilled, e.g. variables must start with
"_" or an uppercase letter ("Lu" category).

"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}".

Quited strings and character lists may contain hexadecimally encoded
characters using the "\xXX" and "\uXXXX" escape sequences, in
addition to the usual "\t", "\n" and "\\".

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.                        [FGHC]
    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.                        [FGHC]
    big(N, 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 and FLENG are 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 more 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 (The book is available
online, see the "References" section for details).

Strand is a subset of FGHC, but only provides assignment instead
of output unification.  FGHC is very similar to "KL1"[6], which was a
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"[12] 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. [FGHC]

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). [FGHC]

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).                                            [FGHC]

is expanded into the following.

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

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.                                  [FGHC]

is interpreted as follows:

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

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.                              [FGHC]

is interpreted as follows:

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

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. The PCN Language

"PCN" (Program Composition Notation) is a language developed by the
designers of "Strand", having a more conventional C-derived syntax,
but providing the same level of parallelism as the more traditional
variants of concurrent logic languages. The language is described
in detail in the PCN manual[10] and in [11], a tutorial can be found
in the "doc" directory of the distribution in the file "PCN-tutorial.txt",
or enter

	flengdoc PCN-tutorial

to view it at the command line.

The following statement types are supported:

    "<procedure-name>(<term>, ...)" (procedure call)
        Invokes the given procedure, passing zero or more arguments.

    "<identifier> = <term>"
        Defines a definitional variable.

    "<identifier>[<expr>] = <term>"
        Defines the definition variable in a tuple element.

    "<identifier> := <expression>"
        Assigns the result of an expression to a mutable variable.

    "<identifier> ++ <term> ++ ..."
        Pushes the terms or expressions onto an argument pair (see
        the description of "variable pairs" below).

    "<identifier>[<expr>] := <expression>"
        Sets an array element to the result of an expression.

    "<identifier> over <start> .. <end> :: <statement>"
    "<identifier> over <list> :: <statement>"
        Iterates over the range of numbers <start> to <end> (inclusive)
        or over elements of a list, executing <statement>, with
        <identifier> bound to the current value during the execution of
        the statement.

    "{<designator> <statement>, ...}"
        Nested composition, where <designator> is one of ";", "||' or
        "?".

    "if(<guard>, ...) <statement> [else <statement>]"
        Syntactic sugar for

            "{? <guard>, ... -> <statement>, default -> <statement> }"

    "let <guard>, ... -> <statement>"
        Syntactic sugar for

            "{? <guard>, ... -> <statement>, default -> <fail with error> }"

    "with <identifier> = <term> , ... -> <statement>"
        Invokes <statement> in a task with dynamic bindings.
        Task-bindings are inherited by sub-tasks and can be accessed with
        "binding/{2,3}" and "call_handler/{1,2}".

    "<identifier>.<identifier2> <-- <term>"
        Field update notation for structs. <Identifier> must be
        a paired argument.

    "<identifier>[ <expr> ] <-- <term>"
    	Indexed update notation for lists and tuples. <Identifier>
    	must be a paired argument.

Guards are used to test conditions and execute the associated
statement when all guards in a rule are successful. The following
guard types are supported:

    "<identifier> ?= <pattern>"
        Match the contents of <identifier> with <pattern> and succeed
        if the structure of the value matches.

    "<type>(<term>)"
        Succeeds when the given <term> is of the designated type. Valid
        types are "int", "double", "tuple", "list", "number", "string",
        "atomic", "remote", "module" or "data".

    "known(<term>)"
        Succeeds if <term> is a non-variable value or a bound variable.

    "unknown(<term>)"
        Succeeds if <term> is an unbound variable.

    "<term> == <term>"
    "<term> != <term>"
        Test terms or expressions for equality. The arguments may be
        numerical expressions.

    "<expression> > <expression>"
    "<expression> < <expression>"
    "<expression> >= <expression>"
    "<expression> <= <expression>"
        Test expressions by numerical comparison.

    "idle"
        Succeeds when the current thread is inactive (i.e. no other
        processes are running).

    "default"
        Succeeds when no other guard does. If another guard in the same
        choice composition suspends, then the whole composition suspends
        and the default guard waits until all other choices do not
        succeed even after resumption.

The special guards "idle" and "default" can not be combined with other
guards in the same clause.

A "term" stands for a structured data object or an arithmetic expression.
Data objects are

    "[<element>, ...]"
        Lists of arbitrary values.

    "{<element>, ...}"
        Tuples, fixed-length sequences of one or more values.

    <number>

    <string>

    <character>

    <identifier>

Term-elements inside "[...]" and "{...}" may also be expressions, but
these are not evaluated and represented as structured data in the form
of tuples, lists and atomic objects (strings, numbers and variables),
mostly identical to FGHC terms. Note that not all valid PCN
expressions are allowed inside terms, specifically "lambda"
expressions ("``(...) -> ...").

Elements may be integer or floating point numbers, following the usual
syntactic conventions (numeric base prefixes "0x...", "0..." and "0b..."
are allowed for hexadecimal, octal or binary integer literals), characters
(using the "'<char>'" notation, as in C) and strings, character sequences
enclosed in double quotes ("..."). Note that strings are not equivalent
to character arrays.

Numbers may contain "'" as a separator for readability if the preceding
and following character is a digit (in whatever base the number is given).

Expressions may be any of the following:

    "<expr> + <expr>"
    "<expr> - <expr>"
    "<expr> * <expr>"
    "<expr> / <expr>"
    "<expr> % <expr>"
    "<expr> & <expr>"
    "<expr> | <expr>"
    "<expr> ^ <expr>"
    "<expr> >> <expr>"
    "<expr> << <expr>"
        Arithmetic and logic expressions and the "modulo" operator.
        Operator precedence is as in C.

    "abs(<expr>)"
        Absolute value.

    "sin(<expr>)"
    "cos(<expr>)"
    "tan(<expr>)"
    "atan(<expr>)"
    "log(<expr>)"
    "exp(<expr>)"
    "real_fractional_part(<expr>)"
    "real_integer_part(<expr>)"
    "floor(<expr>)"
    "ceiling(<expr>)"
    "round(<expr>)"
    "truncate(<expr>)"
    "sqrt(<expr>)"
        Operations on real numbers and trigonometic functions.

    "max(<expr>, <expr>)"
    "min(<expr>, <expr>)"
        Maximum and minimum, if either of the arguments is a floating-point value,
        then the result will be as well.

    "real(<expr>)"
    "integer(<expr>)"
        Convert reals to integers and vice versa.

    "rnd(<expr>)"
    "rnd()"
        Return a random integer between 0 and <expr>-1 or a uniformly
        distributed random real between 0 and 1.

    "-<expr>"
        Negation.

    "~<expr>"
        logical inverse.

    "`(<identifier>, ...) -> <statement>"
        "Lambda" expression: returns a string or tuple that can executed
        using the metacall notation ("`...`") and then runs the statement
        body on invocation via "call/{1,2,3}", "apply/2" or using the
        "metacall" syntax ("`...`"). May not be used inside a guard.

    "``<identifier>``"
    "``<identifier>(<term>, ...)``"
        A callable reference to a procedure in the local module, equivalent
        to a lambda expression that simply passes all arguments to the named
        procedure, optionally with a number of implicit arguments.
        May not be used inside a guard, but may be a term-element.

    "length(<expr>)"
        Returns the length of an array, string, list or tuple, for
        arguments of any other type 1 is returned.

    "tail(<expr>")
        Returns the tail element in a linked list.

    "<identifier>"
        A definitional or mutable variable.

    "<identifier1>.<identifier2>"
    	Field-reference for structs.

    "<identifier>[<expr>]"
        References an array, list, string or tuple element. May be used
        as an assignment target for arrays and as a definition target
        for lists and tuples, if the indexed element refers to an
        unassigned variable.

    "<function-name>(<term>, ...)"
        A function procedure call. Note that function calls are not
        allowed inside a guard expression. Meta-calls using "`...`"
        are supported.

    "<literal>"
        An integer, float or character literal.

The "`...`" notation allows constructing procedure calls dynamically,
the "@" notation allows executing a procedure in another thread. Code in
separately compiled modules is called using the "<module>:..." prefix,
as in FGHC. See the tutorial, the PCN manual[10] and the PCN Primer[11] for more
information.

Declarations of the form

    -<declaration>(...)                                         [PCN]

are available as in FGHC and have the same meaning. Note that
the "include" directive is passed on to the FLENG backend and
does not include PCN code, to do that use the "#include" form
of the C preprocessor.

PCN programs have access to the same primitives as FGHC code and
the "foreign_call" operation can be used in the same manner. PCN
code can call FGHC or Strand predicates and vice versa. Note that
arguments passed to library primitives and non-PCN modules follow
call-by-value semantics, as FGHC/Strand/FLENG code has no notion
of mutable variables as implemented by PCN. To ensure seamless
interoperability, use the

    -fleng_library([module1, ...])                              [PCN]

declaration for separately compiled modules that are not written
in PCN. The PCN compiler automatically declares the standard library
modules provided in this manner, so no declaration is needed.

Where primitives and standard library operations require strings
or character lists, char- and int-arrays are usually accepted as well
where character lists are taken as UTF-8 encoded byte arrays
ant int-arrays as sequences of UNICODE code points.

The main differences to the language described in [10] and [11] are
as follows:

- Single line comments ("// ...") are supported.

- Added support for closure-like meta-expressions ("`(...) -> <block>"
  and "``<call>``".

- Quantification over lists has been added.

- Numeric literals in hex, octal, binary and character notation,
  compatible to C are provided.

- Tuples may not be empty, the empty tuple is identical to the
  empty list.

- The "in" operator is not supported. It's meaning is not yet clear
  to me.

- Expressions support negation (unary "-") and all arithmetic, conversion
  and trigonometric functions supported by FGHC.

- Lists and tuples are distinct types.

- The full meta call form ("`<id>`") takes a tuple as argument,
  where the first element is the name of the procedure.

- Meta-calls may not refer to primitives.

- Remote calls (using the "@" notation) always pass mutable arguments
  by value, with the exception of arrays.

- The PCN compiler detects multiple assignments to mutable variables
  in parallel compositions, but not modifications caused when mutable
  variables are passed to PCN procedures and modified subsequently.

- The "@" notation allows Strand peer names (the identifiers "fwd", "bwd",
  "north", "east", "south" and "west") in addition to integer
  expressions. The "nodes()" and "topology()" functions are not available.
  Numerical peer indexes starts at 1.

- All FGHC type tests are available and have the same semantics as in FGHC.

- Mutable variables may have the "byte" type. "char" can hold a full
  UNICODE code point and thus defines a 32-bit integer. "byte"
  represents unsigned octets.

- The "port" type is not supported.

- Numerical guards fail with an error if given non-numerical arguments,
  this stricter type discipline is considered more robust than the
  behaviour given in [10] which makes the guards silently fail.

- Procedures of the same name but different arity (number of arguments)
  are distinguished and can exist alongside each other.

- The argument to "length()" may be a term.

- Array declarations that do not refer to arguments may contain a
  literal integer size specifier or refer to a mutable argument
  variable, but not to a definitional or non-argument variable.

- Changes to mutable non-array function arguments are not visible in
  the caller.

- Choices must always be enclosed in "{? ... }", even if they only
  contain a single clause. This implementation provides "if...else..."
  and "let" as a more convenient notations, the latter may also be used
  as the body of a procedure.

- Multiple "default" clauses in choice compositions may be present
  and are combined into a single clause.

- Ordering guards (">", "<", ">=" and "<=") only compare numerically,
  arrays are not compared element-wise, as specified in [11].

- The binary integer operators "&", "|", "^", ">>" and "<<" are
  supported.

- In declarations of local array variables the size specifier may
  refer to an argument, which must be a declared mutable variable.

- The primitives listed in [10] are only partially available, the
  set of primitive operations that can be used is fully equivalent to
  the primitives available for FGHC. See the reference documentation
  (or "flengdoc") for details.

- Variable pairs, the "++" operator and the update operators "+=", ...
  are implementation-specific extensions to PCN.

- Embedding of C/C++ code sections.

A BNF definition of the syntax supported by this PCN compiler
can be found in the file "doc/pcn.bnf" of the source distribution.


VI. Builtin Primitives and Support Libraries

The separate document "LIBRARY" describes the available primitive
operations and library definitions available in FGHC code. The
flengdoc(1) tool can be used to search and extract reference
documentation from the command line. Enter

    flengdoc modules

To see a list of the available library modules.

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, PCN 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 (FGHC: abc, 'a string', PCN: "..."), not a character
list. If a primitive accepts both a string or a character list in an
argument position, it specifically says so.

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

* Precedence and associativity of infix operators in FGHC:

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

* Precedence and associativity of infix operators in PCN:

        Operator        Associativity

        - ~             fy              Highest precdence

        * / %           xfx

        + -             yfx

        << >>           xfx

        & | ^           yfx

        == != > < >=
        <= := =         xfx             Lowest precedence


VII. FGHC Programming Tips

1. 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).                     [FGHC]
    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).               [FGHC]
    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.                          [FGHC]

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).         [FGHC]

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

In PCN, writing sequential code is straightforward, but it should
be kept in mind that parallel code is usually more efficient than
sequential code, as the compilation strategy and run-time system is
optimized towards parallel execution of code. Sequential execution
requires additional internal machinery to ensure proper order which
has a small, but non-trivial overhead.

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

3. 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.                   [FGHC]

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). [FGHC]

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.                  [FGHC]

4. 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).                   [FGHC]

    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) :- ...                             [FGHC]
    merge(S, [Y|S2]) :- ...                             [FGHC]

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.

5. 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(_) | ...                        [FGHC]

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                                                 [FGHC]
    -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
    $ ./a.out &
    $ ./b.out hello world
    a received: [hello, world]
    $ ./b.out and more
    a received: [and, more]

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.

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

7. 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) :-                               [FGHC]
        open_port(P, S),
        <create resource R>
        wait(S, R).

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

    create_resource(p) {||                              [PCN]
        open_port(p, s),
        <create resource R>
        {? s == [] -> <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.

8. Speeding up calls to other modules

Cross-module invocations are performed dynamically, using a cache
for saving the resolved target address in subsequent calls from
the same site. To further speed up direct calls to other modules,
you can generate a special "link" file holding labels designating
the location of the external call target. Use it like this:

    % foo.ghc:                                          [FGHC]
    -initialization(main).
    main :- bar:foo.

    % bar.ghc:
    -module(bar).
    foo :- writeln(foo).

    $ fleng -e bar.ghc                      # generates "bar.link"
    $ fleng -c -link bar.link bar.ghc       # generates "bar.o"
    $ fleng foo.ghc -link bar.link bar.o
    $ ./a.out
    foo

    /* foo.pcn: */                                      [PCN]
    main(argc, argv, exit_code) {; bar:foo() }

    /* bar.pcn: */
    -module(bar)
    foo() {; writeln("foo") }

    $ fleng -e bar.pcn                      # generates "bar.link"
    $ fleng -c -link bar.link bar.pcn       # generates "bar.o"
    $ fleng foo.pcn -link bar.link bar.o
    $ ./a.out
    foo

Note that compiling "bar.ghc"/"bar.pcn" to an object module needs to
see the link file so that additional globally visible entry-points
are produced in the output file.


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

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". You can also use the
"trace/{1,2}" primitive to enable logging for specific tasks only.

Additionally, information about the overall status of the program
can be logged, when the "+STATS" or "+HEAPSTATS" run time options are
given. Statistics about memory use and process load are collected and
can be subsequently filtered and analyzed. 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.

Finally, compiled programs can be interactively debugged using a
built-in read-eval-print loop, enabled by the run-time option
"+INTERACTIVE", which ignores the initialization goal of a program
and directly enters the library operation "eval:repl/0" (To use
this mode, the program must be compiled with the "-i" option).

In interactive mode you can enter and evaluate a restricted
subset of FGHC terms. All primitives are available augmented with
a number of convenience operations, enter

    flengdoc eval

for more information about the available forms.

The "+LOAD" run-time option is similar to "+INTERACTIVE" but
accepts a filename and evaluates the FGHC terms in the file
until the end of the file is reached, using the library operation
"eval:load/{1,2}".

PCN code can be debugged in the same manner, but the terms allowed
in interactive mode must follow FGHC syntax. This basically means
strings are enclosed in single quotes ('...'), variables must
begin with an uppercase letter or underscore ("_") and argument
terms are not evaluated. PCN functions are internally prefixed
with "function " (note the whitespace) and receive an implicit
first argument for the result:

    $ cat a.pcn
    main() {
      writeln(square(3))
    }
    function square(x) {return(x * x)}
    $ fleng -i a.pcn
    $ ./a.out +INTERACTIVE
    > 'function square'(R, 3), q(R)
    9
    >

Variables used in the entered terms keep their value, once bound
and can be referenced in terms entered at a later point in time.


IX. 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
    Array           Box&            Parent Array$

    *: 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 raw cell holding a pointer to the storage and length/type
       information
    $: either the empty list or a reference to the array for which
       this array is a "view" (section)

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

To call native code from FGHC, Strand 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>').                      [FGHC]
    -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 this:

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

Note that PCN does not use the "foreign" declaration, as you can
embed and call C/C++ code directly and also has access to C
preprocessor definitions.

In PCN calls to unknown procedures without explicit module prefix
will be treated as calls to externally linked C code, passing mutable
variables, arrays, strings and floating point values by reference.
The compiler and run-time system will try to ensure appropriate
"boxes" holding immediate values are created as needed, but very
little error checking is done. Passing mutable variables of the
wrong type or modifying non-mutable and non-array arguments
destructively is a recipe for disaster. The mapping of argument
types to C is as follows:

    PCN                     C

    string                  char * (UTF-8 encoding, zero-terminated)
    integer                 long *
    mutable variable or array:
        long                long *
        int                 int *
        short               short *
        char                unsigned char *
        double              double *
    term                    opaque pointer to FLENG object

C functions can modify mutable variables, arrays or references to
array elements, but the effect of changes to arguments that do
not represent is undefined (and is likely to be fatal).

In PCN verbatim code can be directly embedded into the source file
by using the "C" or "C++" code section markers, which must be given
in double quotes, directly at the beginning of the line:

	main() 												[PCN]
	long t; {
		gettime(t),
		writeln(t)
	}

	"C":
	void gettime(long *t) {
		*t = time(NULL);
	}

Code markers may be "C", "C++" or "PCN". "C++" overrides any
other foreign-language section markers - the wrapper code will
be compiled as C++ if at least one "C++" section exists. "PCN"
will switch back to PCN code. Note that the C preprocessor
will already have processed the code in the foreign language
section.

Verbatim C code and generated C stubs are written to a file named
"NAME~foreign.c" where "NAME" is the basename of the compiled source
file (use the "-foreign" option to override the name). Compilation and
linking of this file is done by the "fleng" compiler script
automatically when producing an executable file. Should the target
file be an object module, then you need to link the
"NAME~foreign.o" file yourself into your final executable.

Compiled FGHC, Strand and PCN code always uses the C ABI and
does not respect C++ name-mangling. If you want to call embedded
C++ code, you must declare it to have C linkage using the
`extern "C"' qualifier.


X. 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:

- [PCN] The C preprocessor does not treat terms as distinct expressions,
  so macro expansions will split arguments in surprising ways, e.g.:

    #define foo(x) writeln(x)
    main() { foo([1, 2]) }

  This will fail, as "[1" and "2]" are treated as separate arguments.
  As a workaround you can enclose the list in parentheses to make the
  preprocessor treat it as a single macro argument. In many cases
  you can also use variadic macros to circumvent this restriction:

    #define foo(...) writeln(__VA_ARGS__)
    :

- The generated code is too slow and too big.

- There is currently not mechanism for catching errors, failed
  run-time errors (with the exception of certain I/O related
  system call failures) 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.


XI. Code Repository

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

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


XII. 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
    This book can also be downloaded here:

        http://www.call-with-current-continuation.org/files/strand-book.pdf

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

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

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

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

[10] "Parallel programming with PCN"
    Ian Foster and Steven Tuecke
    https://digital.library.unt.edu/ark:/67531/metadc1310344/

[11] "A Primer for Program Composition Notation."
    Chandy, K. Mani and Taylor, Stephen (1990),
    http://resolver.caltech.edu/CaltechCSTR:1990.cs-tr-90-10

[12] "KL1 to C compiler system: KLIC (version 3.011)"
    Kazunori UEDA, Waseda University
    Publicly available at: https://github.com/GunterMueller/KLIC

[13] "The Joy of Concurrent Logic Programming"
     Felix Winkelmann
     http://www.call-with-current-continuation.org/articles/the-joy-of-concurrent-logic-programming.txt


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


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

Also visit the IRC channel "#fleng" on https://libera.chat/ if
you have questions or need advice.