_______ _______ __ _ ______ |______ | |______ | \ | | ____ | |_____ |______ | \_| |_____| User Manual Version: 5 I. Introduction This document describes an implementation of the "FLENG" programming language as described in [1]. FLENG is a very minimal and low-level concurrent logic language descending from Concurrent Prolog. The implementation described here provides a FLENG compiler that generates assembly language for x86-64 and ARM machines on UNIX or BSD systems. Additionally a front end for "Flat Guarded Horn Clauses" (FGHC)[2] is provided, which is a slightly higher level and more convenient language. II. Usage The compiler is invoked by using the "fleng" driver script: fleng [-Vwhkdc] [CCOPT ...] [-m MODULE] [-I DIRECTORY] FILENAME [-o OUTFILE] [OBJECTS ...] The script takes FLENG or FGHC source files and generates assembler, buinary 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. -m MODULE Specifies the name of the compiled module. If no module name is given the module name defaults to "" (empty). -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. Note that enabling debug information has a small runtime-speed overhead. -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. 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 source file. All compiled executables accept a number of runtime command line options to enable debugging output and override internal settings: [+HELP] [+LOG ] [-LOGX ] [+HEAP ] [+GOALS ] [+TIMESLICE ] [+LOGFILE ] [+THREADS ] [+STATS ] [+STAT_TICKS ] [+HEAPSTATS ] ... [--] ... +LOG Enable logging for all threads specified by , where bit 1 corresponds to thread 1 and so on. +LOGX Enable explicit logging with "log/1" for all threads specified by , where bit 1 corresponds to thread 1 and so on. +HEAP 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 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 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 Specifies the number of threads to be used and defaults to 1. +TIMESLICE 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 Write statistics to the log file for all threads selected by the . The statistics are given in textual format and have the following format: ## G Q S C THREAD gives the ordinal number of the thread, starting at 1. TICKS is the number of internal clock ticks of the thread. ACTUIVE 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 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 Enable heap statistics, similar to "+STATS". The format is as follows: #$ T L V TUPLES, LISTS and VARS 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. +HELP Shows runtime option usage information. -- Disables any further runtime option processing. 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 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, but logic variables can only be bound by explicit unification in the body. If an argument variable (a variable occurring in the clause head) refers to a component of a data structure contained in a currently unbound logic variable, 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. 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", "unify", "true", "call", "=" and "foreign_call", described later in this manual. There are further undocumented primitives which are used for translated FGHC code. Toplevel declarations have the following form: -declaration(Argument, ...). Currently supported declarations in FLENG are "include/1", "initialization/1", "threads/1" and "uses/1", which are described below. Some additional declarations exist for internal use but are not documented here. 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. 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 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. 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. % or "otherwise" 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. The main differences between FGHC and Prolog can be summarized as follows: - FGHC has no backtracking: once a rule head matches and the guards succeed, all remaining solutions are abandoned. - All goals of a rule are executed in parallel, in an arbitrary order. - FGHC has no general unification - rule 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 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. 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 runtime 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". * Primitives by group: Control ,/2 call/1 apply/2 true/0 when/2 Unification =/2 assign/3 unify/3 deref/2 Conversion number_to_list/3 number_to_list/4 string_to_float/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 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/3 delete_file/2, rmdir/2 open_file/3, file_exists/2 chmod/3 Input/Output listen/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/1 getpid/1 current_seconds/1 signal/3 clock/3, timer/3, cancel_timer/2, restart_timer/3 randomize/2 error/1 log/1, log/2 Threads threads/1 self/1 idle_thread/1 @/2 Ports open_port/2 send/2 send/3 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 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 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 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. X = Y Equivalent to "unify(_, X, Y)". See "unify/3" for more information. In FLENG a failed unification will silently be ignored, variables in X or Y may be partially bound. In FGHC a failed unification will signal an error. 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(TERM?, LIST?) Appends the arguments in LIST to TERM, which should be a string or a tuple, and invokes it with "call/1". 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. call(TERM?) Invokes the process specified by TERM which must be a tuple or string and must refer to a user-defined process definition. TERM may refer to a module-qualified term. When a variable appears in place of a body goal, it is treated as an invocation of "call/1" with that variable as its argument. cancel_timer(ID?, DONE^) Cancels and removes the timer identifier by ID, previously created by calling "timer/3" or "clock/3" and unifies DONE 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 DONE with "false". 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?, 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 runtime 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 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 sqrt x - Square root sin x - Sine (radians) cos x - Cosine (radians) integer x - Convert float to integer float 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 float results if one of the arguments is a float. "and", "or", "xor", "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 < floats < strings < lists < tuples < ports < modules Integers and floats 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. See "is/2" for a more convenient way to perform arithmetic computations. current_seconds(SECONDS^) Unifies SECONDS with the current UNIX timestamp in seconds since 00:00, Jan. 1, 1970. 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?, 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. 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_type(FILENAME?, TYPE^) Unifies TYPE with the string "file", "directory", "link", "fifo" or "socket" depending on what type of file FILENAME refers to. If the file does not exist, an error is signaled. 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. 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(EXITCODE?) Terminates the program with the given exit code, which must be an integer. 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. 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 float(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 rnd Pseudo random float betwwen 0 and 1 floor(X) ceiling(X) round(X) Rounding operations sin(X) cos(X) Trigonometry max(X, Y) min(X, Y) Return greater or lesser argument Random numbers returned by "rnd" are uniformly distributed. 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_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. 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. number_to_list(NUMBER?, LIST^, TAIL?) number_to_list(NUMBER?, BASE?, LIST^, TAIL?) Converts the integer or float 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 on of the strings "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^, 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?, 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 and signals an error if FILENAME does not refer to a symbolic link or the file does not exist. 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. restart_timer(ID?, MS?, DONE^) Modifies the timeout for the timer identified by ID and previously created by calling "timer/3" or "clock/3" and unifies DONE 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 DONE with "false". 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. 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^, DONE^) Installs a signal handler for the signal with the name given by the string SIGNAL, which should 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. string_to_float(STRING?, FLOAT^) 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" runtime 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(RESULT^, X?, Y?) Unifies X with Y and unifies RESULT with the string "true" or "false", depending on whether the unification succeeded or failed. Partial variable bindings on unification failure are not restored. 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_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 numericall 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 "!". float(X) Succeeds if X is a floating point number. 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. 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, 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: include(FILENAME) Includes the contents of FILENAME at the current toplevel position in the compiled file. initialization(PROCESSLIST) Declares the on startup, the processes given will be spawned. PROCESSLIST should be a string or a list of strings. 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. * Precedence and associativity of infix operators: The precedence and associativity of numerical operators follows the usual ISO Prolog syntax: Operator Associativity + - \ fy Highest precedence * / << >> yfx + - /\ \/ >< yfx : xfy = == =\= =:= \== @< @> @=< @>= is > < >= =< @ xfx , xfy | xfy :- xfx Lowest precedence VI. Debugging To analyse runtime errors, execution can be logged to standard error or a dedicated file using the "+LOG" runtime 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. "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. VII. 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 Float 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_(FL_TCB *tcb, FL_VAL, ...)) "" 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. "fleng.h" provides the base API for communicating with the runtime system in "libfleng": FL_VAL fl_nil, fl_true, fl_false Global variables holding predefined strings for the empty list and the strings "true" and "false". void fl_unify_result(FL_TCB *tcb, FL_VAL val, FL_VAL dest) Unifies "val" with "dest", increasing reference counts as necessary. void fl_assign(FL_TCB *tcb, FL_VAL x, FL_VAL var) Assigns "x" to "var", which must be an unbounded variable or a variable holding a value identical to "x". The reference count of "x" will be automatically increased on assignment. This function should normally only be used when "var" is expected to be unbound. FL_VAL fl_alloc_cell(FL_TCB *tcb, FL_VAL car, FL_VAL cdr) Allocates a memory cell by taking it from the pool of unused cells of this thread. "car" and "cdr" are the initial values of the head and tail of the cell. The reference count of the returned cell will be zero and the tag will not be initialized, yet. FL_VAL fl_alloc_float(FL_TCB *tcb, double x) Allocate a floating point number. Due to alignment reasons, you should always use this function to allocate floating point values. The reference count of the returned datum is zero. void fl_write(FL_TCB *tcb, FILE *fp, FL_VAL x) Writes the value of "x" to the given file stream. The operation may block the current thread. FL_VAL fl_mkstring(char *str, int len) Create a new string by interning it into the internal string table. "str" should point to the characters of the string and "len" hold the number of characters. The value returned will not share storage with "str". Note that interning is a slow operation and storage for interned strings is never recovered. int fl_nthreads(void) Returns the number of threads in the system. The "fleng-util.h" header file, which is installed along with the FLENG/FGHC compilers and runtime libraries, provides a number of macros and static functions to simplify working with data objects: CAR(x) CDR(x) Access the head and tail of the cell "x". COUNT(x) Returns the reference count of "x". TAG(x) Returns the type code of a cell, which is a 32 bit integer with the actual type located in the highest 8 bits. For tuples, the topmost bit is set and bits 25 to 31 contain the arity of the tuple (the number of arguments, not including the head). CHECK_INT(x) CHECK_STRING(x) CHECK_LIST(x) CHECK_NUMBER(x) CHECK_TUPLE(x) CHECK_VAR(x) Perform run-time checks on the type of "x". Note that "x" is not dereferenced. LIST(x, head, tail) Declares local variables of type "FL_VAL" with the names "head" and "tail" and initializes them to the result of extracting and dereferencing the head and tail parts of the list "x". TUPLE(x, name, arity, args) Declares local variables "name", "arity" and "args" of types "FL_VAL", "int" and "FL_VAL", respectively, and initializes them to the result of extracting the name, arity and arguments of the tuple "x". FLOAT(x, n) Declares the local variable "n" of type "double" containing the numerical value of "x", which may be an integer or float. addref(x) Increases the reference count of "x" and returns "x". deref(x) If "x" is not a variable, returns it unchanged. If it is a variable, then "deref" returns the value to which the variable is bound. If unbound, the variable is returned. It is crucial to dereference all arguments passed to a foreign function to make sure variables holding data work as expected. Note that unbound variable accesses do not suspend - this has to be handled in FGHC/FLENG code by using "!" or "data/1". mklist(tcb, car, cdr) Returns a freshly allocated list cell with the given head and tail values. Reference counts for the arguments are automatically increased. mktuple(tcb, name, arity, args) Returns a freshly allocated tuple with the given name, arity and argument list. The reference counts for the argument list is automatically increased. mkvar(tcb) Returns a freshly allocated unbound variable. mkcharlist(tcb, charptr, length, tail) Creates a list of the character codes found at "charptr", holding "length" elements and terminated by "tail", and returns the list. stringify(tcb, str, lenptr) Converts "str", which should be a string or character list into a temporary character buffer and returns a pointer to the buffer. The buffer is only valid until the foreign call using this operation returns. "lenptr" is a pointer to an "int" holding the length the the temporary string. The string is terminated by a '\0' character. unref(tcb, x) Decreases the reference count and releases "x" when the count reaches zero. In the latter case the cell is no longer valid and should not be used. VIII. 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: - No measure is taken if a message sent from one thread to another exceeds the size of the message buffer. To handle this is technically not a problem but just hasn't been implemented yet. - Some attempt is made to prohibit the creation of circular data structures, but not all edge cases are likely to be addressed. IX. 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 X. License This software was written by Felix L. Winkelmann and has been released into the public domain. Do with it whatever you like. XI. 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