<?xml version="1.0" encoding="UTF-8"?>

<!-- ====================================================================== -->
<!-- = chapter-5.xml                                                      = -->
<!-- = afnix programmer's guide chapter 5                                 = -->
<!-- ====================================================================== -->
<!-- = This  program  is  free  software; you  can redistribute it and/or = -->
<!-- = modify it provided that this copyright notice is kept intact.      = -->
<!-- = This program is distributed in the hope that it will be useful but = -->
<!-- = without  any  warranty;  without  even  the  implied  warranty  of = -->
<!-- = merchantability or fitness for  a  particular purpose. In no event = -->
<!-- = shall  the  copyright  holder be liable for any  direct, indirect, = -->
<!-- = incidental  or special  damages arising  in any way out of the use = -->
<!-- = of this software.                                                  = -->
<!-- ====================================================================== -->
<!-- = copyright (c) 1999-2019 - amaury darsch                            = -->
<!-- ====================================================================== -->

<chapter volume="1" number="5">
  <title>Advanced concepts</title>

  <p>
    This chapter covers advanced concepts of the writing
    system. The first subject is the exception model. The second
    subject covers some properties of the namesets in the context of
    the interpreter object. The thread sub-system is then described
    along with the synchronization mechanism. Finally, some notes
    related to the functional system are given at the end of this
    chapter.
  </p>

  <!-- exceptions -->
  <section>
    <title>Exception</title>

    <p>
      An <em>exception</em> is an unexpected change in the execution
      flow. The exception model is based on a mechanism which throws
      the exception to be caught by a handler. The mechanism is also
      designed to be compatible with the native "C++" implementation.
      <ie>Exception</ie>
    </p>
    
    <!-- throwing an exception -->
    <subsect>
      <title>Throwing an exception</title>
      
      <p>
	An exception is thrown with the reserved keyword
	<code>throw</code>. When an exception is thrown, the normal flow
	of execution is interrupted and an object used to carry the
	exception information is created. Such exception object is
	propagated backward in the call stack until an exception handler
	catch it.<ie>throw</ie>
      </p>
      
      <example>
	if (not (number-p n)) 
        (throw "type-error" "invalid object found" n)
      </example>

      <p>
	The example above is the general form to throw an exception. The
	first argument is the <em>the exception id</em>. The second
	argument is the <em>exception reason</em>. The third argument is
	the <em>exception object</em>. The exception id and reason are
	always a string. The exception object can be any object which is
	carried by the exception. The reserved keyword
	<code>throw</code> accepts 0 or more arguments.
      </p>
      
      <example>
	throw              
	throw "type-error" 
	throw "type-error" "invalid argument"
      </example>

      <p>
	With 0 argument, the exception is thrown with the exception id
	set to "user-exception". With one argument, the argument is the
	exception id. With 2 arguments, the exception id and reason are
	set. Within a try block, an exception can be thrown again by
	using the exception object represented with the
	<code>what</code> symbol.<ie>what</ie>
      </p>
      
      <example>
	try {
          ...
        } {
          println "exception caught and re-thrown"
	  throw what
	}
      </example>
    </subsect>
    
    <!-- exception handler -->
    <subsect>
      <title>Exception handler</title>
      
      <p>
	The special form <code>try</code> executes a form and catch
	an exception if one has been thrown. With one argument, the form
	is executed and the result is the result of the form execution
	unless an exception is caught. If an exception is caught, the
	result is the exception object. If the exception is a native
	one, the result is nil.<ie>try</ie>
      </p>

      <example>
	try (+ 1 2)
	try (throw)
	try (throw "hello")
	try (throw "hello" "world")
	try (throw "hello" "world" "folks")
      </example>
      
      <p>
	In its second form, the <code>try</code> reserved keyword can
	accept a second form which is executed when an exception is
	caught. When an exception is caught, a new nameset is created
	and the special symbol <code>what</code> is bounded with the
	exception object. In such environment, the exception can be
	evaluated.
      </p>

      <table>
	<title>Symbol bound to the exception object</title>
	<tr><th>Symbol</th><th>Description</th></tr>
	<tr><td>eid</td>   <td>Exception id</td></tr>
	<tr><td>name</td>  <td>Exception file name</td></tr>
	<tr><td>line</td>  <td>Exception line number</td></tr>
	<tr><td>about</td> <td>Exception extended reason</td></tr>
	<tr><td>reason</td><td>Exception reason</td></tr>
	<tr><td>object</td><td>Exception object</td></tr>
      </table>
      
      <example>
	try (throw "hello")              
          (eval what:eid)
	try (throw "hello" "world")      
          (eval what:reason)
	try (throw "hello" "world" 2000) 
          (eval what:object)
      </example>
      
      <p>
	Exceptions are useful to notify abruptly that something went
	wrong. With an untyped language, it is also a convenient
	mechanism to abort an expression call if some arguments do not
	match the expected types.
	<ie>eid</ie><ie>about</ie><ie>reason</ie>
      </p>

      <example>
	# protected factorial
	const fact (n) {
          if (not (integer-p n)) 
	    (throw "number-error" "invalid argument in fact")
            if (== n 0) 1 (* n (fact (- n 1)))
	  }
	  try (fact 5) 0
	  try (fact "hello") 0
      </example>
    </subsect>
  </section>

  <!-- nameset -->
  <section>
    <title>Nameset</title>
    
    <p>
      A nameset is created with the reserved keyword
      <code>nameset</code>. Without argument, the <code>nameset</code>
      reserved keyword creates a nameset without setting its
      parent. With one argument, a nameset is created and the parent set
      with the argument.<ie>nameset</ie>
    </p>
    
    <example>
      const nset (nameset)
      const nset (nameset ...)
    </example>
    
    <!-- default nameset -->
    <subsect>
      <title>Default namesets</title>
      
      <p>
	When a nameset is created, the symbol <code>.</code> is
	automatically created and bound to the newly created nameset. If
	a parent nameset exists, the symbol <code>..</code> is also
	automatically created. The use of the current nameset is a
	useful notation to resolve a particular name given a hierarchy
	of namesets.<ie>.</ie><ie>..</ie>
      </p>
      
      <example>
	trans a 1 # 1
	block {
          trans   a (+ a 1) # 2
          println ..:a 1    # 1
        }
        println a           # 1
      </example>
    </subsect>
    
    <!-- nameset and inheritance -->
    <subsect>
      <title>Nameset and inheritance</title>
      
      <p>
	When a nameset is set as the super object of an instance, some
	interesting results are obtained. Because symbols are resolved
	in the nameset hierarchy, there is no limitation to use a
	nameset to simulate a kind of multiple inheritance. The
	following example illustrates this point.
      </p>

      <example>
	const   cls (class)
	const   ins (cls)
	const   ins:super (nameset)
	const   ins:super:value 2000
	const   ins:super:hello "hello world "
	println ins:hello ins:value # hello world 2000
      </example>
    </subsect>
  </section>

  <!-- delayed evaluation -->
  <section>
    <title>Delayed Evaluation</title>

    <p>
      The engine provides a mechanism called <em>delayed
      evaluation</em>. Such mechanism permits the encapsulation of a
      form to be evaluated inside an object called a <em>promise</em>.
      <ie>Delayed evaluation</ie><ie>promise</ie>
    </p>

    <!-- creating a promise -->
    <subsect>
      <title>Creating a promise</title>
      
      <p>
	The reserved keyword <code>delay</code> creates a
	<em>promise</em>. When the promise is created, the associated
	object is not evaluated. This means that the promise evaluates
	to itself.<ie>delay</ie>
      </p>

      <example>
	const a (delay (+ 1 2))
	promise-p a # true
      </example>

      <p>
	The previous example creates a promise and store the argument
	form. The form is not yet evaluated. As a consequence, the symbol
	<code>a</code> evaluates to the promise object.
      </p>
    </subsect>

    <!-- forcing a promise -->
    <subsect>
      <title>Forcing a promise</title>

      <p>
	The reserved keyword <code>force</code> the evaluation of a
	promise. Once the promise has been forced, any further call will
	produce the same result. Note also that, at this stage, the
	promise evaluates to the evaluated form.<ie>force</ie>
      </p>

      <example>
	trans   y 3
	const   l ((lambda (x) (+ x y)) 1)
	assert  4 (force l)
	trans   y 0
	assert  4 (force l)
      </example>
    </subsect>
  </section>

  <!-- enumeration -->
  <section>
    <title>Enumeration</title>
    
    <p>
      Enumeration, that is, named constant bound to an object, can be
      declared with the reserved keyword <code>enum</code>. The
      enumeration is built with a list of literal and evaluated as is.
      <ie>enum</ie>
    </p>

    <example>
      const  e    (enum E1 E2 E3)
      assert true (enum-p e)
    </example>

    <p>
      The complete enumeration evaluates to an <code>Enum</code>
      object. Once built, enumeration item evaluates by literal and
      returns an <code>Item</code> object.<ie>Item</ie>
    </p>

    <example>
      assert true   (item-p e:E1)
      assert "Item" (e:E1:repr)
    </example>

    <p>
      Items are comparable objects. Only items can be compared. For a
      given item, the source enumeration can be obtained with the
      <code>get-enum</code> method.<ie>get-enum</ie>
    </p>

    <example>
      # check for item equality
      const i1 e:E1
      const i2 e:E2
      assert true  (i1:== i1)
      assert false (== i1 i2)
      # get back the enumeration
      assert true (enum-p (i1:get-enum))
    </example>
  </section>
  
  <!-- logger -->
  <section>
    <title>Logger</title>
    
    <p>
      The <code>Logger</code> class is a message logger that stores
      messages in a buffer with a level. The default level is the
      level 0. A negative level generally indicates a warning or an
      error message but this is just a convention which is not
      enforced by the class. A high level generally indicates a less
      important message. The messages are stored in a circular
      buffer. When the logger is full, a new message replace the
      oldest one. By default, the logger is initialized with a 256
      messages capacity that can be re-sized.<ie>Logger</ie>
    </p>
    
    <example>
      const log    (Logger)
      assert true  (logger-p log)
    </example>
    
    <p>
      When a message is added, the message is stored with a time-stamp
      and a level. The time-stamp is used later to format a
      message. The <code>length</code> method returns the number of
      logged messages. The <code>get-message</code> method returns a
      message by index. Because the system operates with a circular buffer,
      the <code>get-message</code> method manages the indexes in such way that
      the old messages are accessible with the oldest index. For example,
      even after a buffer circulation, the index 0 will point to the
      oldest message. The <code>get-message-level</code> returns the
      message level and the <code>get-message-time</code> returns the
      message posted time.<ie>Logger message</ie>
    </p>
    
    <example>
      const mesg (log:get-message 0)
    </example>
    
    <p>
      In term of usage, the logger facility can be conveniently used
      with other derived classes. The standard i/o module provides
      several classes that permits to manage logging operations in a
      convenient way.
    </p>
  </section>
  
  <!-- interpreter -->
  <section>
    <title>Interpreter</title>

    <p>
      The interpreter is by itself a special object with specialized
      methods which do not have equivalent using the standard
      notation. The interpreter is always referred with the special
      symbol <code>interp</code>. The following table is a summary of
      the symbols and methods bound to the interpreter.
      <ie>Interpreter object</ie><ie>interp</ie>
    </p>

    <table>
      <title>Interpreter built-in symbols</title>
      <tr>
	<th>Symbol</th><th>Description</th>
      </tr>
      <tr><td>argv</td>          <td>Command arguments vector</td></tr>
      <tr><td>os-name</td>       <td>Operating system name</td></tr>
      <tr><td>os-type</td>       <td>Operating system type</td></tr>
      <tr><td>version</td>       <td>Full version</td></tr>
      <tr><td>loader</td>        <td>The interpreter loader</td></tr>
      <tr><td>resolver</td>      <td>The interpreter resolver</td></tr>
      <tr><td>afnix-uri </td>    <td>Official uri name</td></tr>
      <tr><td>program-name</td>  <td>Interpreter program name</td></tr>
      <tr><td>major-version</td> <td>Major version number</td></tr>
      <tr><td>minor-version</td> <td>Minor version number</td></tr>
      <tr><td>patch-version</td> <td>Patch version number</td></tr>
      <tr><td>machine-size</td>  <td>The interpreter machine size</td></tr>
    </table>

    <table>
      <title>Interpreter built-in methods</title>
      <tr>
	<th>Symbol</th><th>Description</th>
      </tr>
      <tr><td>dup</td>           <td>duplicate the interpreter</td></tr>
      <tr><td>roll</td>          <td>run the interpreter loop</td></tr>
      <tr><td>wait</td>          <td>Wait for normal threads</td></tr>
      <tr><td>load</td>          <td>Load a file and execute it</td></tr>
      <tr><td>launch</td>        <td>Launch a normal thread</td></tr>
      <tr><td>daemon</td>        <td>Launch a daemon thread</td></tr>
      <tr><td>library</td>       <td>Load and initialize a library</td></tr>
      <tr><td>read-line</td>     <td>Get an input stream line</td></tr>
      <tr><td>read-passphrase</td> <td>Get an input stream passphrase</td></tr>
      <tr><td>set-absolute-precision</td> <td>Set absolute precision</td></tr>
      <tr><td>set-relative-precision</td> <td>Set relative precision</td></tr>
      <tr><td>get-absolute-precision</td> <td>Get absolute precision</td></tr>
      <tr><td>get-relative-precision</td> <td>Get relative precision</td></tr>
    </table>
    
    <!-- arguments vector -->
    <subsect>
      <title>Arguments vector</title>
      
      <p>
	The <code>interp:argv</code> qualified name evaluates to a
	vector of strings. Each argument is stored in the vector during
	the interpreter initialization.
	<ie>Arguments vector</ie><ie>argv</ie>
      </p>

      <example>
	zsh&gt; axi hello world
	(axi) println (interp:argv:length) # 2
	(axi) println (interp:argv:get 0)  # hello
      </example>
    </subsect>
    
    <!-- interpreter version-->
    <subsect>
      <title>Interpreter version</title>

      <p>
	Several symbols can be used to track the interpreter version and the
	operating system. The full version is bound to the
	<code>interp:version</code> qualified name. The full version is
	composed of the <em>major</em>, <em>minor</em> and
	<em>patch</em> number. The operating system name is bound to the
	qualified name <code>interp:os-name</code>. The operating system
	type is bound to the <code>interp:os-type</code>.
	<ie>Interpreter version</ie><ie>System name and type</ie>
      </p>
      
      <example>
	println "major number   : " interp:major-version
	println "minor number   : " interp:minor-version
	println "patch number   : " interp:patch-version
	println "version number : " interp:version
	println "system name    : " interp:os-name
	println "system type    : " interp:os-type
	println "official uri   : " interp:afnix-uri
      </example>
    </subsect>

    <!-- load method -->
    <subsect>
      <title>Method load</title>
      
      <p>
	The <code>interp:load</code> method loads and execute a
	file. The interpreter interactive command session is suspended
	during the execution of the file. In case of error or if an
	exception is raised, the file execution is terminated. The
	process used to load a file is governed by the <em>file
	resolver</em>. Without extension, a compiled  file is searched
	first and if not found a source file is searched.
	<ie>load</ie>
      </p>
    </subsect>

    <!-- library method -->
    <subsect>
      <title>Method library</title>
      
      <p>
	The <code>interp:library</code> method loads and initializes a
	library. The interpreter maintains a list of opened
	library. Multiple execution of this method for the same library
	does nothing. The method returns the library object.
	<ie>library</ie>
      </p>

      <example>
	interp:library "afnix-sys"
	println "random number: " (afnix:sys:get-random)
      </example>
    </subsect>

    <!-- interpreter duplication -->
    <subsect>
      <title>Method dup</title>
      
      <p>
	The interpreter can be duplicated with the help of the
	<code>dup</code> method. Without argument, a clone of the
	current interpreter is made and a terminal object is attached to
	it. When used in conjunction with the <code>roll</code> method,
	this approach permits to create an interactive interpreter. The
	<code>dup</code> method also accepts a terminal object.
	<ie>dup</ie><ie>roll</ie>
      </p>

      <example>
	# duplicate the interpreter
	const si (interp:dup)
	# change the primary prompt
	si:set-primary-prompt "(si)"
      </example>
    </subsect>
    
    <!-- interpreter loop -->
    <subsect>
      <title>Method roll</title>

      <p>
	The interpreter loop can be run with the <code>roll</code>. The
	loop operates by reading the interpreter input stream. If the
	interpreter has been cloned with the help of the
	<code>dup</code> method, this method provides a convenient way
	to operate in interactive mode. The method is not called
	<em>loop</em> because it is a reserved keyword and starting a
	loop is like having the ball rolling.
	<ie>Interpreter loop</ie>
      </p>
      
      <example>
	# duplicate the interpreter
	const si (interp:dup)
	# loop with this interpreter
	si:roll
      </example>
    </subsect>

    <!-- interpreter wait -->
    <subsect>
      <title>Method wait</title>

      <p>
	The interpreter can wait for all normal threads to
	complete. When invoked, the interpreter monitors all normal
	threads and wait unil the terminate normally. This is a
	standard synchronization method in a multithreaded environment.
      </p>
      
      <example>
	# create a thread
	launch f
	# wait for completion
	interp:wait
      </example>
    </subsect>
  </section>

  <!-- librarian object -->
  <section>
    <title>Librarian object</title>
    
    <p>
      A <em>librarian file</em> is a special file that acts as a
      containers for various files. A librarian file is created with the
      <command>axl</command> -- cross librarian --utility. Once a
      librarian file is created, it can be added to the  
      interpreter resolver. The file access is later performed
      automatically by name with the standard interpreter
      <code>load</code> method.
      <ie>Librarian</ie>
    </p>
    
    <!-- creating a librarian -->
    <subsect>
      <title>Creating a librarian</title>
      
      <p>
	The <command>axl</command> utility is the preferred way to
	create a librarian. Given a set of files, <command>axl</command>
	combines them into a single one.
	<ie>axl</ie>
      </p>
      
      <example>
	zsh: axl -h
	usage: axl [options] [files]
	           [h]      print this help message
	           [v]      print version information
	           [c]      create a new librarian
	           [x]      extract from the librarian
	           [s]      get file names from the librarian
	           [t]      report librarian contents
	           [f] lib  set the librarian file name
      </example>

      <p>
	The <option>c</option> option creates a new librarian. The
	librarian file name is specified with the <option>f</option>
	option.
      </p>

      <example>
      zsh: axl -c -f librarian.axl file-1.als file-2.als
      </example>

      <p>
	The previous command combines <file>file-1.als</file> and
	<file>file-2.als</file> into a single file called
	<file>librarian.axl</file> . Note that any file can be included
	in a librarian.
      </p>
    </subsect>

    <!-- using the librarian -->
    <subsect>
      <title>Using the librarian</title>
      
      <p>
	Once a librarian is created, the interpreter <option>-i</option>
	option can be used to specify it. The <option>-i</option> option
	accepts either a directory name or a librarian file. Once the
	librarian has been opened, the interpreter <code>load</code>
	method can be used as usual.
      </p>
      
      <example>
	zsh&gt; axi -i librarian.axl
	(axi) interp:load "file-1.als"
	(axi) interp:load "file-2.als"
      </example>
      
      <p>
	The librarian acts like a <em>file archive</em>. The interpreter
	file resolver takes care to extract the file from the librarian
	when the <code>load</code> method is invoked.
      </p>
    </subsect>
      
    <!-- librarian contents -->
    <subsect>
      <title>Librarian contents</title>

      <p>
	The <command>axl</command> utility provides the
	<option>-t</option> and <option>-s</option> options to look at the
	librarian contents. The <option>-s</option> option returns all
	file name in the librarian. The <option>-t</option> option
	returns a one line description for each file in the librarian.
      </p>

      <example>
	zsh: axl -t -f librarian.axl
	--------       1234 file-1.als
	--------       5678 file-2.als
      </example>
      
      <p>
	The one line report contains the file flags, the file size and
	the file name. The file flags are not used at this time. One
	possible use in the future is for example, an <em>auto-load
	bit</em> or any other useful things.
      </p>
    </subsect>

    <!-- librarian extraction -->
    <subsect>
      <title>Librarian extraction</title>
      
      <p>
	The <option>-x</option> option permits to extract file from the
	librarian. Without any file argument, all files are
	extracted. With some file arguments, only those specified files
	are extracted.
      </p>

      <example>
	zsh: axl -x -f librarian.axl
	zsh: axl -x -f librarian.axl file-1.als
      </example>
    </subsect>
  </section>

  <!-- librarian object -->
  <section>
    <title>Librarian object</title>
    
    <p>
      The <code>Librarian</code> object can be used as a convenient
      way to create a collection of files or to extract some of them.
    </p>
    
    <!-- output librarian -->
    <subsect>
      <title>Output librarian</title>
      
      <p>
	The <code>Librarian</code> object is a standard
	object. Its predicate is <code>librarian-p</code>. Without
	argument, a librarian is created in <em>output mode</em>. With a
	string argument, the librarian is opened in <em>input mode</em>,
	with the file name argument. The output mode is used to create a
	new librarian by adding file into it. The input mode is created
	to read file from the librarian.
      </p>
      
      <example>
	# create a new librarian
	const lbr (Librarian)
	# add a file into it
	lbr:add "file-1.als"
	# write it
	lbr:write "librarian.axl"
      </example>
      
      <p>
	The <code>add</code> method adds a new file into the
	librarian. The <code>write</code> method the full librarian as a
	single file those name is <code>write</code> method argument.
      </p>
    </subsect>
    
    <!-- input librarian -->
    <subsect>
      <title>Input librarian</title>
      
      <p>
	With an argument, the librarian object is created in input
	mode. Once created, file can be read or extracted. The
	<code>length</code> method -- which also work with an output
	librarian --  returns the number of files in the librarian. The
	<code>exists-p</code> predicate returns true if the file name
	argument exists in the librarian. The <code>get-names</code> 
	method returns a vector of file names in this librarian. The
	<code>extract</code> method returns an input stream object for
	the specific file name.
      </p>
      
      <example>
	# open a librarian for reading
	const lbr (Librarian "librarian.axl")
	# get the number of files
	println (lbr:length)
	# extract the first file
	const is (lbr:extract "file-1.als")
	# is is an input stream - dump each line
	while (is:valid-p) (println (is:readln))
      </example>

      <p>
	Most of the time, the librarian object is used to extract file
	dynamically. Because a librarian is mapped into the memory at
	the right offset, there is no worry to use big librarian, even
	for a small file. Note that any type of file can be used, text
	or binaries.
      </p>
    </subsect>
  </section>

  <!-- file resolver -->
  <section>
    <title>File resolver</title>
    
    <p>
      The <em>file resolver</em> is a special object used by the
      interpreter to resolve file path based on the search path. The 
      resolver uses a mixed list of directories and librarian files in
      its search path. When a file path needs to be resolved, the search
      path is scanned until a matched is found. Because the librarian
      resolution is integrated inside the resolver, there is no need to
      worry about file extraction. That process is done
      automatically. The resolver can also be used to perform any kind
      of file path resolution. <ie>File resolver</ie>
    </p>
    
    <!-- resolver object -->
    <subsect>
      <title>Resolver object</title>

      <p>
	The resolver object is created without argument. The
	<code>add</code> method adds a directory path or a librarian
	file to the resolver. The <code>valid</code> method checks for
	the existence of a file. The <code>lookup</code> method returns
	an input stream object associated with the object.
      </p>
      
      <example>
	# create a new resolver
	const rslv (Resolver)
	assert true (resolver-p rslv)
	
	# add the local directory on the search path
	rslv:add "."
	
	# check if file test.als exists
	# if this is ok - print its  contents
	if (rslv:valid-p "test.als") {
          const is (rslv:lookup "test.als")
	  while (is:valid-p) (println (is:readln))
        }
      </example>
    </subsect>
  </section>

  <!-- thread  operations-->
  <section>
    <title>Thread operations</title>
    
    <p>
      The interpreter is a multi-threaded engine with a native implementation
      of objects locking. A thread is started with the reserved
      keyword <code>launch</code>. The execution is completed when all
      threads have terminated. This means that the master thread (i.e
      the first thread) is suspended until all other threads have
      completed their execution.<ie>Thread</ie><ie>launch</ie>
    </p>
    
    <!-- starting a thread -->
    <subsect>
      <title>Starting a thread</title>
      
      <p>
	A thread is started with the reserved keyword
	<code>launch</code>. The form to execute in a thread is the 
	argument. The simplest thread to execute is the <code>nil</code>
	thread.
      </p>

      <example>
	launch (nil)
      </example>

      <p>
	There exists an alternate mechanism to start a thread with the 
	reserved keyword <code>launch</code> and a thread object. Such
	mechanism is used when using deferred thread object creation or
	a thread generator object known as a <em>thread set</em>.
	<ie>Thread set</ie>
      </p>
    </subsect>
    
    <!-- thread object and result -->
    <subsect>
      <title>Thread object and result</title>
      
      <p>
	When a thread terminate, the thread object holds the result of
	the last executed form. The thread object is returned by the
	<code>launch</code> command. The <code>thread-p</code>
	predicates returns <code>true</code> if the object is a thread
	descriptor.<ie>Thread object</ie>
      </p>

      <example>
	const thr (launch (nil))
	println   (thread-p thr) # true
      </example>
      
      <p>
	The thread result can be obtained with the help of
	the <code>result</code> method. Although the result can be
	accessed at any time, the returned value will
	be <code>nil</code> until the thread as completed its execution.
      </p>

      <example>
	const thr (launch (nil))
	println   (thr:result)   # nilp
      </example>
      
      <p>
	Although the engine will ensure that the result is
	<code>nil</code> until the thread has completed its execution,
	it does not mean that it is a reliable approach to test until
	the result is not <code>nil</code>. The engine provides various
	mechanisms to synchronize a thread and eventually wait for its
	completion.
      </p>
    </subsect>
  </section>

  <!-- shared objects -->
  <section>
    <title>Shared objects</title>
    
    <p>
      The whole purpose of using a multi-threaded environment is to
      provide a concurrent execution with some shared variables. 
      Although, several threads can execute concurrently without sharing
      data, the most common situation is that one or more global
      variable are accessed -- and even changed -- by one or more
      threads. Various scenarios are possible. For example, a variable
      is changed by one thread, the other thread just read its
      value. Another scenario is one read, multiple write, or even more
      complicated, multiple read and multiple write. In any case, the
      interpreter subsystem must ensure that each objects are in a good
      state when such operation do occur.<ie>Shared objects</ie>
      
      The engine provides an automatic synchronization mechanism for
      global objects, where only one thread can modify an object, but
      several thread can read it. This mechanism known as
      <em>read-write locking</em> guarantees that there is only one
      writer, but eventually multiple reader. When a thread starts to
      modify an object, no other thread are allowed to read or write
      this object until the transaction has been completed. On the
      opposite, no thread is allowed to change (i.e. write) an object,
      until all thread which access (i.e. read)  the object value have
      completed the transaction. Because a context switch can occur at
      any time, the object read-write locking will ensure a safe
      protection during each concurrent access.<ie>Locking</ie>
    </p>
    
    <!-- shared protection access -->
    <subsect>
      <title>Shared protection access</title>
      
      <p>
	We illustrate the previous discussion with an interesting
	example and some variations around it. Let's consider a form
	which increase an integer object and another form which decrease
	the same integer object. If the integer is initialized to 0, and
	the two forms run in two separate threads, we might expect to
	see the value bounded by the time allocated for each thread. In
	other word, this simple example is a very good illustration of
	your machine scheduler.
      </p>

      <example>
	# shared variable access
	const var 0
	# increase method
	const incr nil {
	  while true (println "increase: " (var:= (+ var 1)))
	}
	# decrease method
	const decr nil {
	  while true (println "decrease: " (var:= (- var 1)))
	}
	# start both threads
	launch (decr)
	launch (incr)
      </example>

      <p>
	In the previous example, <code>var</code> is initialized to
	0. The <code>incr</code> thread increments <code>var</code>
	while the <code>decr</code> thread decrements
	<code>var</code>. Depending on the operating system, the result
	stays bounded within a certain range. The previous example can
	be changed by using the main thread or a third thread to print
	the variable value. The end result is the same, except that
	there is more threads competing for the shared variable.
      </p>
      
      <example>
	# shared variable access
	const var 0	
	# incrementer, decrementer and printer
	const incr nil (while true (var:= (+ var 1)))
	const decr nil (while true (var:= (- var 1)))
	const prtv nil (while true (println "value = " var))
	# start all threads
	launch (decr)
	launch (incr)
	launch (prtv)
      </example>
    </subsect>
  </section>

  <!-- synchronization -->
  <section>
    <title>Synchronization</title>

    <p>
      Although, there is an automatic synchronization mechanism
      for reading or writing an object, it is sometimes necessary to
      control the execution flow. There are basically two techniques to
      do so. First, protect a form from being executed by several
      threads. Second, wait for one or several threads to complete their
      task before going to the next execution step.
      <ie>Synchronization</ie>
    </p>
    
    <!-- form synchronization -->
    <subsect>
      <title>Form synchronization</title>
      
      <p>
	The reserved keyword <code>sync</code> can be used to
	synchronize a form. When a form, is synchronized, the
	engine guarantees that only one thread will execute this
	form.
      </p>

      <example>
	const print-message (code mesg) (
          sync {
	    errorln "error  : " code
	    errorln "message: " mesg
	  }
        )
      </example>

      <p>
	The previous example creates a gamma expression which make sure
	that both the error code and error message are printed in one
	group, when several threads call it.
      </p>
    </subsect>

    <!-- thread completion -->
    <subsect>
      <title>Thread completion</title>

      <p>
	The other piece of synchronization is the thread completion
	indicator. The thread descriptor contains a method called
	<code>wait</code> which suspend the calling thread until the
	thread attached to the descriptor has been completed. If the
	thread is already completed, the method returns immediately.
	<ie>Thread completion</ie>
      </p>

      <example>
	# simple flag
	const flag false
	# simple tester
	const ftest (bval) (flag:= bval)
	# run the thread and wait
	const thr (launch (ftest true))
	thr:wait
	assert true flag
      </example>
      
      <p>
	This example is taken from the test suites. It checks that a boolean
	variable is set when started in a thread. Note the use of
	the <code>wait</code> method to make sure the thread has
	completed before checking for the flag value. It is also 
	worth to note that <code>wait</code> is one of the method which
	guarantees that a thread result is valid.
	
	Another use of the <code>wait</code> method can be made with a
	vector of thread descriptors when one wants to wait until all of
	them have completed.
      </p>
      
      <example>
	# shared vector of threads descriptors
	const thr-group (Vector)
	# wait until all threads in the group are finished
	const wait-all nil (for (thr) (thr-group) (thr:wait))
      </example>
    </subsect>

    <!-- complete example -->
    <subsect>
      <title>Complete example</title>

      <p>
	We illustrate the previous discussion with a complete
	example. The idea is to perform a matrix multiplication. A
	thread is launched when when multiplying one line with one
	column. The result is stored in the thread descriptor. A vector
	of thread descriptor is used to store the result.
      </p>

      <example>
	# initialize the shared library
	interp:library "afnix-sys"

	# shared vector of threads descriptors
	const thr-group (Vector)
	# waits until all threads in the group are finished
	const wait-all nil (for (thr) (thr-group) (thr:wait))
      </example>

      <p>
	The group of threads is represented as a vector. Based on the
	the previous discussion, a simple loop that blocks until all
	threads are completed is designed as a simple gamma expression.
      </p>
	
      <example>
	# initializes a matrix with random numbers
	const init-matrix (n) {
          trans i (Integer 0)
	  const m (Vector)
	  do {
	    trans v (m:add (Vector))
	    trans j (Integer)
	    do {
	      v:add (afnix:sys:get-random)
	    } (&lt; (j:++) n)
          } (&lt; (i:++) n)
          eval m
        }
      </example>

      <p>
	The matrix initialization is quite straightforward. The matrix
	is represented as a vector of lines. Each line is also a
	vector of random integer number. It is here worth to note that
	the standard <em>math</em> module provides a native
	implementation of real matrix.
      </p>

      <example>
	# this procedure multiply one line with one column
	const mult-line-column (u v) {
	  assert (u:length) (v:length)
	  trans result 0
	  for (x y) (u v) (result:+= (* x y))
	  eval result
        }

        # this procedure multiply two vectors assuming one 
        # is a line and one is a column from the matrix
        const mult-matrix (mx my) {
          for (lv) (mx) {
	    assert true (vector-p lv)
	    for (cv) (my) {
	      assert true (vector-p cv)
	      thr-group:add (launch (mult-line-column lv cv))
            }
          }
        }
      </example>

      <p>
	The matrix vector multiplication is at the heart of the
	example. Each line-column multiplication is started into a
	thread and the thread object is placed into the thread group
	vector.
      </p>

      <example>
        # check for some arguments
        # note the use of errorln method
        if (== 0 (interp:argv:length)) {
          errorln "usage: axi 0607.als size"
	  afnix:sys:exit 1
	}

	# get the integer and multiply
	const n (Integer (interp:argv:get 0))
	mult-matrix (init-matrix n) (init-matrix n)
	# wait for all threads to complete
	wait-all
	# make sure we have the right number
	assert (* n n) (thr-group:length)
      </example>

      <p>
	The main execution is started with the matrix size as the
	first argument. Two random matrices are then created and the
	multi-threaded multiplication is launched. The main thread is
	blocked until all threads in the thread group are completed.
      </p>
    </subsect>

    <!-- condition variable -->
    <subsect>
      <title>Condition variable</title>

      <p>
	A <em>condition variable</em> is another mechanism to
	synchronize several threads. A condition variable is modeled
	with the <code>Condvar</code> object. At construction, the
	condition variable is initialized to <code>false</code>. A
	thread calling the <code>wait</code> method will block until the
	condition becomes <code>true</code>. The <code>mark</code>
	method can be used by a thread to change the state of a
	condition variable and eventually awake some threads which are
	blocked on it. The following example shows how the main thread
	blocks until another change the state of the condition.
	<ie>Condition variable</ie>
      </p>
      
      <example>
	# create a condition variable
	const cv (Condvar)
	
	# this function runs in a thread - does some 
	# computation and mark the condition variable
	const do-something nil {
          # do some computation
	  ....
	  # mark the condition
	  cv:mark
	}

        # start some computation in a thread
        launch (do-something)

        # block until the condition is changed
        cv:wait-unlock

        # continue here
        ...
      </example>

      <p>
	In this example, the condition variable is created at the
	beginning. The thread is started and the main thread blocks
	until the thread change the state of the condition variable. It
	is important to note the use of the <code>wait-unlock</code>
	method. When the main thread is re-started (after the condition
	variable has been marked), the main thread owns the lock
	associated with the condition variable. The
	<code>wait-unlock</code> method unlocks that lock when the main
	thread is restarted. Note also that the <code>wait-unlock</code>
	method reset the condition variable. if the <code>wait</code>
	method was used instead of <code>wait-unlock</code> the lock
	would still be owned by the main thread. Any attempt by other
	thread to call the mark method would result in the calling
	thread to block until the lock is released.<ie>Condvar</ie>
	
	The <code>Condvar</code> class has several methods which can be
	used to control the behavior of the condition variable. Most of
	them are related to lock control. The <code>reset</code> method
	reset the condition variable. The <code>lock</code> and
	<code>unlock</code> control the condition variable locking. The
	<code>mark</code>, <code>wait</code> and
	<code>wait-unlock</code> method controls the synchronization
	among several threads.
      </p>
    </subsect>
  </section>

  <!-- function expression -->
  <section>
    <title>Function expression</title>

    <p>
      A lambda expression or a gamma expression can be seen like a
      function object with no name. During the evaluation process, the
      expression object is evaluated as well as the arguments -- from
      left to right -- and a result is produced by applying those
      arguments to the function object. An expression can be built
      dynamically as part of the evaluation process.
    </p>

    <example>
      (axi) println ((lambda (n) (+n 1)) 1)
      2
    </example>
    
    <p>
      The difference between a lambda expression and a gamma expression
      is only in the nameset binding during the evaluation process. The
      lambda expression nameset is linked with the calling one, while
      the gamma expression nameset is linked with the top level
      nameset. The use of gamma expression is particularly interesting
      with recursive functions as it can generate a significant
      execution speedup. The previous example will behaves the same with
      a gamma expression.<ie>Function expression</ie>
    </p>

    <example>
      (axi) println ((gamma (n) (+n 1)) 1)
      2
    </example>

    <!-- self reference -->
    <subsect>
      <title>Self reference</title>
      
      <p>
	When combining a function expression with recursion, the need
	for the function to call itself is becoming a problem since that
	function expression does not have a name. For this reason,
	the writing system provides the reserved keyword
	<code>self</code> that is a reference to the function
	expression. We illustrate this capability with the well-known
	factorial expression written in pure functional style.
	<ie>Self reference</ie><ie>self</ie>
      </p>

      <example>
	(axi) println ((gamma (n) 
	  (if (&lt;= n 1) 1 (* n (self (- n 1))))) 5)
	120
      </example>

      <p>
	The use of a gamma expression versus a lambda expression is a
	matter of speed. Since the gamma expression does not have
	free variables, the symbol resolution is not a concern here.
      </p>
    </subsect>
    
    <!-- closed variables -->
    <subsect>
      <title>Closed variables</title>

      <p>
	One of the writing system characteristic is the treatment of
	<em>free variables</em>. A variable is said to be free if it is
	not bound in the expression environment or its children at the
	time of the symbol resolution. For example, the expression
	<code>((lambda (n) (+ n x)) 1)</code> computes the sum of the
	argument <code>n</code> with the free variable
	<code>x</code>. The evaluation will succeeds if <code>x</code>
	is defined in one of the parent environment. Actually this
	example can also illustrates the difference between a
	lambda expression and a gamma expression. Let's consider the
	following forms.<ie>Closed variables</ie>
      </p>
      
      <example>
	trans x 1
	const do-print nil {
          trans x 2
	  println ((lambda (n) (+ n x)) 1)
        }
      </example>
      
      <p>
	The gamma expression <code>do-print</code> will produce
	<code>3</code> since it sums the argument <code>n</code> bound
	to 1, with the free variable <code>x</code> which is defined in
	the calling environment as <code>2</code>. Now if we rewrite the
	previous example with a gamma expression the result will be one,
	since the expression parent will be the top level environment
	that defines <code>x</code> as 1.
      </p>

      <example>
	trans x 1
	const do-print nil {
          trans x 2
	  println ((gamma (n) (+ n x)) 1)
        }
      </example>

      <p>
	With this example, it is easy to see that there is a need to be
	able to determine a particular symbol value during the
	expression construction. Doing so is called <em>closing a
	variable</em>. Closing a variable is a mechanism that binds into
	the expression a particular symbol with a value and such symbol
	is called a <em>closed variable</em>, since its value is closed
	under the current environment evaluation. For example, the
	previous example can be rewritten to close the symbol
	<code>x</code>.
      </p>
      
      <example>
	trans x 1
	const do-print nil {
          trans x 2
	  println ((gamma (n) (x) (+ n x)) 1)
        }
      </example>

      <p>
	Note that the list of closed variable immediately follow the
	argument list. In this particular case, the function
	<code>do-print</code> will print <code>3</code> since
	<code>x</code> has been closed with the value <code>2</code> has
	defined in the function <code>do-print</code>.
      </p>
    </subsect>

    <!-- dynamic binding -->
    <subsect>
      <title>Dynamic binding</title>
      
      <p>
	Because there is a dynamic binding symbol resolution, it is
	possible to have under some circumstances a free or closed
	variable. This kind of situation can happen when a particular
	symbol is defined under a condition.<ie>Dynamic binding</ie>
      </p>

      <example>
	lambda (n) {
          if (&lt;= n 1) (trans x 1)
	    println (+ n x)
        }
      </example>

      <p>
	With this example, the symbol <code>x</code> is a free variable
	if the argument <code>n</code> is greater than 1. While this
	mechanism can be powerful, extreme caution should be made when
	using such feature.
      </p>
    </subsect>

    <!-- lexical and qualified name -->
    <subsect>
      <title>Lexical and qualified names</title>
      
      <p>
	The basic forms elements are the lexical and qualified
	names. Lexical and qualified names are constructed by the
	parser. Although the evaluation process make that
	lexical object transparent, it is possible to manipulate them
	directly.<ie>Lexical name</ie><ie>Qualified name</ie>
      </p>

      <example>
	(axi) const sym (protect lex)
	(axi) println   (sym:repr)
	Lexical
      </example>

      <p>
	In this example, the <code>protect</code> reserved keyword is
	used to avoid the evaluation of the lexical object named
	<code>lex</code>. Therefore the symbol <code>sym</code> refers
	to a lexical object. Since a lexical -- and a qualified --
	object is a also a literal object, the <code>println</code>
	reserved function will work and print the object name. In fact,
	a literal object provides the <code>to-string</code> method
	that returns the string representation of a literal object.
	<ie>protect</ie>
      </p>

      <example>
	(axi) const sym (protect lex)
	(axi) println   (sym:to-string)
	lex
      </example>
    </subsect>
    
    <!-- symbol and argument access -->
    <subsect>
      <title>Symbol and argument access</title>

      <p>
	Each nameset maintains a table of symbols. A symbol is a binding
	between a name and an object. Eventually, the symbol carries the
	<code>const</code> flag. During the lexical evaluation process,
	the lexical object tries to find an object in the nameset
	hierarchy. Such object can be either a symbol or an
	argument. Again, this process is transparent, but can be
	controlled manually. Both lexical and qualified named object
	have the <code>map</code> method that returns the first object
	associated in the nameset hierarchy.<ie>Symbol access</ie>
      </p>
      
      <example>
	(axi) const obj 0
	(axi) const lex (protect obj)
	(axi) const sym (lex:map)
	(axi) println   (sym:repr)
	Symbol
      </example>

      <p>
	A symbol is also a literal object, so the <code>to-string</code>
	and <code>to-literal</code> methods will return the symbol
	name. Symbol methods are provided to access or modify the symbol
	values. It is also possible to change the <code>const</code>
	symbol flag with the <code>set-const</code> method.
      </p>

      <example>
	(axi) println (sym:get-const)
	true
	(axi) println (sym:get-object)
	0
	(axi) sym:set-object true
	(axi) println (sym:get-object)
	true
      </example>

      <p>
	A symbol name cannot be modified, since the name must be
	synchronized with the nameset association. On the other hand, a
	symbol can be explicitly constructed. As any object, the
	<code>=</code> operator can be used to assign a symbol
	value. The operator will behaves like the
	<code>set-object</code> method.
      </p>

      <example>
	(axi) const sym (Symbol "symbol")
	(axi) println sym
	symbol
	(axi) sym:= 0
	(axi) println (eval sym)
	0
      </example>
    </subsect>

    <!-- closure -->
    <subsect>
      <title>Closure</title>

      <p>
	As an object, the <code>Closure</code> can be manipulated
	outside the traditional declarative way. A closure is a special
	object that holds an argument list, a set of closed variables
	and a form to execute. The mechanic of a closure evaluation has
	been described earlier. What we are interested here is the
	ability to manipulate a closure as an object and eventually
	modify it. Note that by default a closure is constructed as a
	lambda expression. With a boolean argument set to true the same
	result is obtained. With false, a gamma expression is created.
      </p>

      <example>
	(axi) const f (Closure)
	(axi) println (closure-p f)
	true
      </example>

      <p>
	This example creates an empty closure. The default closure is
	equivalent to the <code>trans f nil nil</code>. The same can be
	obtained with <code>const f (Closure true)</code>. For a gamma
	expression, the following  forms are equivalent, <code>const f
	(Closure false)</code> and <code>const f nil
	nil</code>. Remember that it is <code>trans</code> and
	<code>const</code> that differentiate between a lambda and a
	gamma expression. Once the closure object is defined, the
	<code>set-form</code> method can be used to bind a form.
      </p>

      <example>
	# the simple way
	trans f nil (println "hello world")
	# the complex way
	const f    (Closure)
	f:set-form (protect (println "hello world"))
      </example>
      
      <p>
	There are numerous situations where it is desirable to mute
	dynamically a closure expression. The simplest one is the
	closure that mute itself based on some context. With the use of
	<code>self</code>, a new form can be set to the one that is
	executed. Another use is a mechanism call <em>advice</em>, where
	some new computation are inserted prior the closure
	execution. Note that appending to a closure can lead to some
	strange results if the existing closure expression uses
	<em>return</em> special forms. In a multi-threaded environment,
	the ability to change a closure expression is particularly
	handy. For example a special thread could be used to monitor
	some context. When a particular situation develops, that threads
	might trigger some closure expression changes. Note that
	changing a closure expression does not affect the one that is
	executed. If such change occurs during a recursive call, that
	change is seen only at the next call.<ie>advice</ie>
      </p>
    </subsect>
  </section>
</chapter>
