commit 8801d9c4e3af7650048288393dd7b409a25154c2
Author: Max Rottenkolber <max@mr.gy>
Date:   Mon Nov 20 18:22:24 2017 +0100

    software/erlangen: 204166b Improve documentation of LINK and EXIT.

diff --git a/software/erlangen/api.mk2 b/software/erlangen/api.mk2
index 0e66713..74ace01 100644
--- a/software/erlangen/api.mk2
+++ b/software/erlangen/api.mk2
@@ -120,7 +120,7 @@
 
   *Arguments and Values:*
 
-  _reason_—an _object_.
+  _reason_—an _object_. The default is {:kill}.
 
   _agent_—an _agent_. The default is the _calling agent_.
 
@@ -156,14 +156,15 @@
   {link} _links_ the _calling agent_ to _agent_. After two _agents_ are
   _linked_ they behave as follows:
 
-  When the _calling agent_ exits it will attempt to kill _agent_ with the
-  _exit reason_ of the _calling agent_.
+  When the _calling agent_ exits, an _exit message_ with the _exit
+  reason_ of the _calling agent_ is delivered to the _linked agent_.
 
-  When _agent_ exits, and _mode_ is {:link} it will attempt to kill the
-  _calling agent_ with the _exit reason_ of _agent_.
+  When the linked _agent_ exits, and _mode_ is {:link}, an _exit message_
+  with the _exit reason_ of the _linked agent_ is delivered to the
+  _calling agent_.
 
-  When _agent_ exits, and _mode_ is {:monitor} it will attempt to send an
-  _exit notification_ to the _calling agent_.
+  When the _linked agent_ exits, and _mode_ is {:monitor}, an _exit
+  notification_ is delivered to the _calling agent_.
 
   An _exit notification_ is of the form
 

commit 80342341516e6ceb335a2bdbb7e191e0eac17ec2
Author: Max Rottenkolber <max@mr.gy>
Date:   Thu Jun 15 21:26:57 2017 +0200

    erlagen/api: minor updates

diff --git a/software/erlangen/api.mk2 b/software/erlangen/api.mk2
index 134ec4d..0e66713 100644
--- a/software/erlangen/api.mk2
+++ b/software/erlangen/api.mk2
@@ -18,6 +18,13 @@
   operation except that the exit reason will be the _agent_ instead of
   the fatal _condition_.
 
+  When an _agent_ is started it _binds_ this variable to its value in the
+  environment where it was spawned, effectively inheriting the _binding_.
+
+  *Affected By:*
+
+  {spawn}
+
  >
 
 
@@ -32,6 +39,13 @@
   {\*default-mailbox-size\*} is the default value of the {:mailbox-size}
   parameter to {spawn}.
 
+  When an _agent_ is started it _binds_ this variable to its value in the
+  environment where it was spawned, effectively inheriting the _binding_.
+
+  *Affected By:*
+
+  {spawn}
+
  >
 
 

commit f8c3ac0ed6255a35c5c6c8dbe13b59c705906b8f
Author: Max Rottenkolber <max@mr.gy>
Date:   Fri May 12 18:46:23 2017 +0200

    software/erlangen/api: minor fix

diff --git a/software/erlangen/api.mk2 b/software/erlangen/api.mk2
index c5ea79e..134ec4d 100644
--- a/software/erlangen/api.mk2
+++ b/software/erlangen/api.mk2
@@ -355,7 +355,7 @@
 
   _function_—a _function designator_ or a _call_.
 
-  _attach_—either {:link}, {:attach}, or {nil}. The default is {nil}.
+  _attach_—either {:link}, {:monitor}, or {nil}. The default is {nil}.
 
   _mailbox-size_—a positive _unsigned integer_. The default is
   {\*default-mailbox-size\*}.

commit 13b681d3934adf399f420f178b4be8ff420b284e
Author: Max Rottenkolber <max@mr.gy>
Date:   Tue Feb 28 19:04:35 2017 +0100

    software/erlangen: documentation updates (857bccf).

diff --git a/software/erlangen/api.mk2 b/software/erlangen/api.mk2
index 2a23807..c5ea79e 100644
--- a/software/erlangen/api.mk2
+++ b/software/erlangen/api.mk2
@@ -108,7 +108,7 @@
 
   _reason_—an _object_.
 
-  _agent_—an _agent_. Default is the _calling agent_.
+  _agent_—an _agent_. The default is the _calling agent_.
 
   *Description*:
 
@@ -186,7 +186,7 @@
 
   _host_—a _host_ as accepted by
   [resolve-address](http://ccl.clozure.com/docs/ccl.html\#f\_resolve-address).
-  The default is {"localhost"}.
+  The default is the local host name as reported by {machine-instance}.
 
   _name_—a _string_. The default is a unique name.
 
@@ -204,6 +204,11 @@
 (spawn 'node)
   #
 
+  *Side Effects:*
+
+  {node} changes the host name of the local node to _host_, which is
+  subsequently used as a default argument to {spawn}.
+
   *Exceptional Situations:*
 
   If _name_ can not be registered \(e.g., because it has already been
@@ -359,7 +364,7 @@
 
   _host_—a _host_ as accepted by
   [resolve-address](http://ccl.clozure.com/docs/ccl.html\#f\_resolve-address).
-  The default is the local host name as reported by {machine-instance}.
+  The default is the host name of the local node.
 
   *Description:*
 
@@ -372,6 +377,10 @@
   If _node_ is _non-nil_ the _agent_ is started on _node_ of _host_
   instead of the local node.
 
+  *Affected By:*
+
+  {node}
+
   *Exceptional Situations:*
 
   If {spawn} fails to start the _agent_ an an _error_ of _type_ {error}
@@ -661,7 +670,7 @@
 
   *Syntax:*
 
-  — Generic Function: *root* _x_
+  — Generic Function: *root* _agent‑tree_
 
   → _agent_
 

commit a0dd7fc947378149f5939c403bdebafa663f75ac
Author: Max Rottenkolber <max@mr.gy>
Date:   Sun Dec 11 21:24:35 2016 +0100

    erlangen/api: updates.

diff --git a/software/erlangen/api.mk2 b/software/erlangen/api.mk2
index f2828cd..2a23807 100644
--- a/software/erlangen/api.mk2
+++ b/software/erlangen/api.mk2
@@ -222,7 +222,7 @@
 
   *Arguments and Values:*
 
-  _timeout_—a positive _number_ denoting a time interval in seconds.
+  _timeout_—a non-negative _real_ denoting a time interval in seconds.
 
   *Description*:
 
@@ -464,11 +464,11 @@
 
   _agent_—an _agent_.
 
-  _messages-received_—a positive _integer_ denoting the number of
+  _messages-received_—a non-negative _integer_ denoting the number of
   messages received by _agent_.
 
-  _messages-dropped_—a positive _integer_ denoting the number of messages
-  dropped by _agent_ because its mailbox was full.
+  _messages-dropped_—a non-negative _integer_ denoting the number of
+  messages dropped by _agent_ because its mailbox was full.
 
   _birthtime_—a _universal time_ denoting the time when _agent_ was
   started.
@@ -546,7 +546,7 @@
   host name, node name, _errors_, and _established_ of the respective
   connection.
 
-  _errors_—a positive _integer_ denoting the number of errors on the
+  _errors_—a non-negative _integer_ denoting the number of errors on the
   matching connection.
 
   _established_—a _universal time_ denoting the time when the matching
@@ -642,8 +642,8 @@
 
   _process_—a _process_.
 
-  _timeout_—a positive _integer_ denoting a time interval in seconds. The
-  default is 1.
+  _timeout_—a non-negative _real_ denoting a time interval in seconds.
+  The default is 1.
 
   _agent_—an _agent_ or {nil}.
 

commit 155758cc76b923a365f0c4e43a97da3fb0bb0e19
Author: Max Rottenkolber <max@mr.gy>
Date:   Fri Dec 9 00:05:38 2016 +0100

    erlangen/api: avoid fixnums.

diff --git a/software/erlangen/api.mk2 b/software/erlangen/api.mk2
index 3d3ab57..f2828cd 100644
--- a/software/erlangen/api.mk2
+++ b/software/erlangen/api.mk2
@@ -464,10 +464,10 @@
 
   _agent_—an _agent_.
 
-  _messages-received_—a positive _fixnum_ denoting the number of messages
-  received by _agent_.
+  _messages-received_—a positive _integer_ denoting the number of
+  messages received by _agent_.
 
-  _messages-dropped_—a positive _fixnum_ denoting the number of messages
+  _messages-dropped_—a positive _integer_ denoting the number of messages
   dropped by _agent_ because its mailbox was full.
 
   _birthtime_—a _universal time_ denoting the time when _agent_ was
@@ -546,7 +546,7 @@
   host name, node name, _errors_, and _established_ of the respective
   connection.
 
-  _errors_—a positive _fixnum_ denoting the number of errors on the
+  _errors_—a positive _integer_ denoting the number of errors on the
   matching connection.
 
   _established_—a _universal time_ denoting the time when the matching
@@ -661,7 +661,7 @@
 
   *Syntax:*
 
-  — Generic Function: *root* _agent‑tree_
+  — Generic Function: *root* _x_
 
   → _agent_
 

commit a8e3decc3569debff3e66147c63ebf5c5cc99919
Author: Max Rottenkolber <max@mr.gy>
Date:   Thu Dec 8 23:54:07 2016 +0100

    erlangen/api: minor fixes.

diff --git a/software/erlangen/api.mk2 b/software/erlangen/api.mk2
index 32b094a..3d3ab57 100644
--- a/software/erlangen/api.mk2
+++ b/software/erlangen/api.mk2
@@ -390,7 +390,7 @@
   *Description:*
 
   Describes an error condition that can occur when using functions with a
-  timeout. It denotes a that the operations was unable to successfully
+  timeout. It denotes a that the operation was unable to successfully
   complete within a given duration.
 
  >
@@ -661,7 +661,7 @@
 
   *Syntax:*
 
-  — Generic Function: *root* _x_
+  — Generic Function: *root* _agent‑tree_
 
   → _agent_
 

commit 76a1289c19097cdb409518021305fcdcec0e26ee
Author: Max Rottenkolber <max@mr.gy>
Date:   Sat Dec 3 01:36:50 2016 +0100

    Updated Erlangen API.

diff --git a/software/erlangen/api.meta b/software/erlangen/api.meta
index fc8a83b..784c3e7 100644
--- a/software/erlangen/api.meta
+++ b/software/erlangen/api.meta
@@ -1,4 +1,4 @@
 :document (:title "Erlangen API Documentation")
 :source (:system :erlangen
-         :api-document (:erlangen))
+         :api-document (:erlangen :erlangen.management))
 :stylesheets ((:media "screen" :href "/site-assets/api.css"))
diff --git a/software/erlangen/api.mk2 b/software/erlangen/api.mk2
index 348bfa7..32b094a 100644
--- a/software/erlangen/api.mk2
+++ b/software/erlangen/api.mk2
@@ -119,9 +119,8 @@
 
   *Exceptional Situations:*
 
-  If _agent_ is not the _calling agent_, and the _exit message_ could not
-  be delivered successfully an _error_ of _type_ {send-error} is
-  signaled.
+  If _agent_ is a _keyword_ that is not registered as a name an _error_
+  of _type_ {simple-error} is signaled.
 
  >
 
@@ -136,7 +135,7 @@
 
   _agent_—an _agent_.
 
-  _mode_—a _keyword_. Either {:link} or {:monitor}. Defaults to {:link}.
+  _mode_—either {:link} or {:monitor}. The default is {:link}.
 
   *Description*:
 
@@ -154,13 +153,7 @@
 
   An _exit notification_ is of the form
 
-  {\(} _agent_ {.} _exit-reason_ {\)}
-
-  where _exit-reason_ is the _exit reason_ of _agent_.
-
-  An _exit reason_ has the following from:
-
-  {\(} _status_ {.} _values_ {\)}
+  {\(} _agent_ _status_ . _values_ {\)}
 
   _status_::= {:ok} \| {:exit}
 
@@ -169,19 +162,17 @@
 
   The _status_ {:exit} indicates that the _agent_ was either killed by
   {exit} or aborted because of an unhandled _condition_ of _type_
-  {serious-condition}, and _values_ will be the _reason_ supplied to
-  {exit} or the _condition object_.
-
-  The attempts to kill or notify _linked agents_ will fail if the
-  respective message can not be delivered to the target _agent_. Any
-  error conditions that arise due to the failure will be silently
-  ignored.
+  {serious-condition}, and _values_ will be the _exit reason_ supplied to
+  {exit}, or the _condition object_.
 
   *Exceptional Situations:*
 
   If _agent_ is the _calling agent_ an _error_ of _type_ {simple-error}
   is signaled.
 
+  If _agent_ is a _keyword_ that is not registered as a name an _error_
+  of _type_ {simple-error} is signaled.
+
  >
 
 
@@ -193,7 +184,9 @@
 
   *Arguments and Values:*
 
-  _host_—a _string_. The default is {"localhost"}.
+  _host_—a _host_ as accepted by
+  [resolve-address](http://ccl.clozure.com/docs/ccl.html\#f\_resolve-address).
+  The default is {"localhost"}.
 
   _name_—a _string_. The default is a unique name.
 
@@ -208,9 +201,16 @@
 
   #code#
 ;; Start talking to remote nodes:
-(spawn '(node))
+(spawn 'node)
   #
 
+  *Exceptional Situations:*
+
+  If _name_ can not be registered \(e.g., because it has already been
+  registered by another node, or because the port mapper is unreachable\)
+  an _error_ of _type_ {error} is signaled, and the node protocol server
+  is killed.
+
  >
 
 
@@ -218,11 +218,11 @@
 
   *Syntax:*
 
-  — Function: *receive* {&key} _timeout_ _poll-interval_
+  — Function: *receive* {&key} _timeout_
 
   *Arguments and Values:*
 
-  _timeout_, _poll-interval_—positive _numbers_.
+  _timeout_—a positive _number_ denoting a time interval in seconds.
 
   *Description*:
 
@@ -232,12 +232,12 @@
   until a message arrives.
 
   If _timeout_ is supplied {receive} will block for at most _timeout_
-  seconds and poll for a message every _poll-interval_ seconds.
+  seconds.
 
   *Exceptional Situations:*
 
-  If _timeout_ is supplied and exceeded an _error_ of _type_ {timeout} is
-  signaled.
+  If _timeout_ is supplied and the specified time interval exceeded an
+  _error_ of _type_ {timeout} is signaled.
 
  >
 
@@ -328,28 +328,13 @@
 
   *Description*:
 
-  {send} delivers _message_ to _agent_.
+  {send} transmits _message_ to _agent_. There is no guarantee as to
+  whether _message_ could be successfully delivered.
 
   *Exceptional Situations:*
 
-  If _message_ could not be delivered successfully an _error_ of _type_
-  {send-error} is signaled.
-
- >
-
-
- < send-error \(Condition Type\)
-
-  *Class Precedence List:*
-
-  {send-error}, {error}, {serious-condition}, {condition},
-  {standard-object}, {t}
-
-  *Description:*
-
-  Describes an error condition that can occur when calling {send}. It
-  denotes a that {send} was unable to successfully deliver the message to
-  the recepient.
+  If _agent_ is a _keyword_ that is not registered as a name an _error_
+  of _type_ {simple-error} is signaled.
 
  >
 
@@ -358,18 +343,24 @@
 
   *Syntax:*
 
-  — Function: *spawn* _function_ {&key} _attach_ _mailbox-size_ _host_
-  _node_
+  — Function: *spawn* _function_ {&key} _attach_ _mailbox-size_ _node_
+  _host_
 
   *Arguments and Values:*
 
   _function_—a _function designator_ or a _call_.
 
-  _attach_—a _keyword_ or {nil}.
+  _attach_—either {:link}, {:attach}, or {nil}. The default is {nil}.
 
   _mailbox-size_—a positive _unsigned integer_. The default is
   {\*default-mailbox-size\*}.
 
+  _node_—a _node name_ or {nil}. The default is {nil}.
+
+  _host_—a _host_ as accepted by
+  [resolve-address](http://ccl.clozure.com/docs/ccl.html\#f\_resolve-address).
+  The default is the local host name as reported by {machine-instance}.
+
   *Description:*
 
   {spawn} starts and returns a new _agent_ with a mailbox capacity of
@@ -378,6 +369,14 @@
   _agent_ is started. Once the _agent_ is started it will execute
   _function_.
 
+  If _node_ is _non-nil_ the _agent_ is started on _node_ of _host_
+  instead of the local node.
+
+  *Exceptional Situations:*
+
+  If {spawn} fails to start the _agent_ an an _error_ of _type_ {error}
+  is signaled.
+
  >
 
 
@@ -392,7 +391,7 @@
 
   Describes an error condition that can occur when using functions with a
   timeout. It denotes a that the operations was unable to successfully
-  complete within a given deadline.
+  complete within a given duration.
 
  >
 
@@ -416,6 +415,9 @@
   If _agent_ is the _calling agent_ an _error_ of _type_ {simple-error}
   is signaled.
 
+  If _agent_ is a _keyword_ that is not registered as a name an _error_
+  of _type_ {simple-error} is signaled.
+
  >
 
 
@@ -442,3 +444,238 @@
 
 >
 
+
+< erlangen.management \(Package\)
+
+ Management extensions for Erlangen including functions for agent tree
+ introspection, and retrieval of statistics for agents and remote
+ connections.
+
+
+ < agent-stats \(Function\)
+
+  *Syntax:*
+
+  — Function: *agent-stats* _agent_
+
+  → _messages-received_, _messages-dropped_, _birthtime_, _deathtime_
+
+  *Arguments and Values:*
+
+  _agent_—an _agent_.
+
+  _messages-received_—a positive _fixnum_ denoting the number of messages
+  received by _agent_.
+
+  _messages-dropped_—a positive _fixnum_ denoting the number of messages
+  dropped by _agent_ because its mailbox was full.
+
+  _birthtime_—a _universal time_ denoting the time when _agent_ was
+  started.
+
+  _deathtime_—a _universal time_ denoting the time when _agent_ exited,
+  or {nil} if _agent_ has not exited.
+
+  *Description:*
+
+  {agent-stats} returns various current statistics for _agent_.
+
+ >
+
+
+ < agent-tree \(Function\)
+
+  *Syntax:*
+
+  — Function: *agent-tree* _agent_
+
+  → _agent-tree_
+
+  *Arguments and Values:*
+
+  _agent_—an _agent_.
+
+  _agent-tree_—an _instance_ of _class_ {agent-tree}.
+
+  *Description:*
+
+  {agent-tree} returns the current _agent-tree_ whose root is _agent_.
+
+ >
+
+
+ < agent-tree \(Class\)
+
+  *Syntax:*
+
+  — Class: *agent-tree* {&key} _root_ _linked_ _monitored_
+
+  *Class Precedence List:*
+
+  {agent-tree}, {standard-object}, {t}
+
+  *Description:*
+
+  Instances of class {agent-tree} denote views of the _agent_ graph at a
+  specific point in time. Their {print-object} method prints an elaborate
+  description of that view when {\*print-readably\*} is {nil}.
+
+ >
+
+
+ < connection-stats \(Function\)
+
+  *Syntax:*
+
+  — Function: *connection-stats* {&optional} _host_ _node_
+
+  → _stats-for-connections_
+
+  → _errors_, _established_
+
+  *Arguments and Values:*
+
+  _host_—a _string_ denoting a _host name_ or {nil}. The default is
+  {nil}.
+
+  _node_—a _string_ denoting a _node name_ or {nil}. The default is
+  {nil}.
+
+  _stats-for-connections_—a _list_ with one element for each matching
+  connection. Each element is a _list_ of four elements containing the
+  host name, node name, _errors_, and _established_ of the respective
+  connection.
+
+  _errors_—a positive _fixnum_ denoting the number of errors on the
+  matching connection.
+
+  _established_—a _universal time_ denoting the time when the matching
+  connection was initially established, or {nil} denoting that the
+  connection has not been established yet.
+
+  *Description:*
+
+  {connection-stats} returns essential statistics for connections to
+  remote nodes. If called without arguments it returns
+  _stats-for-connections_ to all remote nodes to which connections where
+  established. If _host_ is supplied _stats-for-connections_ includes
+  only connections to _host_. If _node_ is supplied {connection-stats}
+  returns _errors_ and _established_ for the connection to _node_.
+
+ >
+
+
+ < flush-messages \(Function\)
+
+  *Syntax:*
+
+  — Function: *flush-messages* {&key} _print-p_ _stream_
+
+  *Arguments and Values:*
+
+  _print-p_—a _generalized boolean_. The default is _true_.
+
+  _stream_—an _output stream_. The default is {\*standard-output\*}.
+
+  *Description:*
+
+  {flush-messages} dequeues messages from the mailbox of the _calling
+  agent_ until there are no more pending messages. If _print-p_ is _true_
+  each dequeued message is printed to _stream_.
+
+ >
+
+
+ < linked \(Generic Function\)
+
+  *Syntax:*
+
+  — Generic Function: *linked* _agent‑tree_
+
+  → _list_
+
+  *Arguments and Values:*
+
+  _agent-tree_—an _object_ of _type_ {agent-tree}.
+
+  _list_—a _list_ of _agents_.
+
+  *Description*:
+
+  {linked} returns a _list_ of _agents_ that are linked to but not
+  monitored by the root _agent_ of _agent-tree_.
+
+ >
+
+
+ < monitored \(Generic Function\)
+
+  *Syntax:*
+
+  — Generic Function: *monitored* _agent‑tree_
+
+  → _subtrees_
+
+  *Arguments and Values:*
+
+  _agent-tree_—an _object_ of _type_ {agent-tree}.
+
+  _subtrees_—a _list_ of _objects_ of _type_ {agent-tree}.
+
+  *Description*:
+
+  {monitored} returns a _list_ of the _subtrees_ whose root _agents_ are
+  monitored by the root _agent_ of _agent-tree_.
+
+ >
+
+
+ < process-agent \(Function\)
+
+  *Syntax:*
+
+  — Function: *process-agent* _process_ {&key} _timeout_
+
+  → _agent_
+
+  *Arguments and Values:*
+
+  _process_—a _process_.
+
+  _timeout_—a positive _integer_ denoting a time interval in seconds. The
+  default is 1.
+
+  _agent_—an _agent_ or {nil}.
+
+  *Description:*
+
+  {process-agent} interrupts _process_ to retrieve its associated
+  _agent_. It returns the respective _agent_ or {nil}. A return value of
+  {nil} indicates that _process_ could not be interrupted within the
+  duration specified by _timeout_.
+
+ >
+
+
+ < root \(Generic Function\)
+
+  *Syntax:*
+
+  — Generic Function: *root* _x_
+
+  → _agent_
+
+  *Arguments and Values:*
+
+  _agent-tree_—an _object_ of _type_ {agent-tree}.
+
+  _agent_—an _agent_.
+
+  *Description*:
+
+  {root} returns the _agent_ that is the root of _agent-tree_.
+
+ >
+
+>
+

commit 0bfdb6567db8774da059f963353fb5a4432b036c
Author: Max Rottenkolber <max@mr.gy>
Date:   Wed Oct 5 15:17:49 2016 +0200

    software/{maxpc,erlangen}/api: minor updates.

diff --git a/software/erlangen/api.mk2 b/software/erlangen/api.mk2
index 6385232..348bfa7 100644
--- a/software/erlangen/api.mk2
+++ b/software/erlangen/api.mk2
@@ -3,7 +3,7 @@
  Distributed, asychronous message passing system for Clozure Common Lisp.
 
 
- < \*agent‑debug\* \(Variable\)
+ < \*agent-debug\* \(Variable\)
 
   *Initial Value:*
 
@@ -21,7 +21,7 @@
  >
 
 
- < \*default‑mailbox‑size\* \(Variable\)
+ < \*default-mailbox-size\* \(Variable\)
 
   *Initial Value:*
 
@@ -112,11 +112,14 @@
 
   *Description*:
 
-  {exit} kills _agent_ with _reason_ as the _exit reason_ of _agent_.
+  {exit} kills _agent_ with _reason_ as the _exit reason_. Subsequent
+  attempts to send messages to _agent_ will fail. If _agent_ is the
+  _calling agent_ it exits immediately, otherwise {exit} delivers an
+  _exit message_ to _agent_.
 
   *Exceptional Situations:*
 
-  If _agent_ is not the _calling agent_, and the _kill message_ could not
+  If _agent_ is not the _calling agent_, and the _exit message_ could not
   be delivered successfully an _error_ of _type_ {send-error} is
   signaled.
 
@@ -159,7 +162,7 @@
 
   {\(} _status_ {.} _values_ {\)}
 
-  _status_::= {:ok}\|{:exit}
+  _status_::= {:ok} \| {:exit}
 
   The _status_ {:ok} indicates that the _agent_ exited normally, and
   _values_ will be a list of its _return values_.
@@ -215,7 +218,7 @@
 
   *Syntax:*
 
-  — Function: *receive* {&key} _timeout_ _poll‑interval_
+  — Function: *receive* {&key} _timeout_ _poll-interval_
 
   *Arguments and Values:*
 
@@ -224,17 +227,15 @@
   *Description*:
 
   {receive} returns the next message for the _calling agent_. If the
-  _mailbox_ of the _calling agent_ is empty, {receive} will block until a
-  message arrives.
+  message is an _exit message_ the _calling agent_ exits immediately. If
+  the _mailbox_ of the _calling agent_ is empty, {receive} will block
+  until a message arrives.
 
   If _timeout_ is supplied {receive} will block for at most _timeout_
   seconds and poll for a message every _poll-interval_ seconds.
 
   *Exceptional Situations:*
 
-  If the _calling agent_ was killed by another _agent_ by use of {exit} a
-  _serious-condition_ of _type_ {exit} is signaled.
-
   If _timeout_ is supplied and exceeded an _error_ of _type_ {timeout} is
   signaled.
 
@@ -337,12 +338,12 @@
  >
 
 
- < send‑error \(Condition Type\)
+ < send-error \(Condition Type\)
 
   *Class Precedence List:*
 
-  {send‑error}, {error}, {serious‑condition}, {condition},
-  {standard‑object}, {t}
+  {send-error}, {error}, {serious-condition}, {condition},
+  {standard-object}, {t}
 
   *Description:*
 
@@ -357,7 +358,7 @@
 
   *Syntax:*
 
-  — Function: *spawn* _function_ {&key} _attach_ _mailbox‑size_ _host_
+  — Function: *spawn* _function_ {&key} _attach_ _mailbox-size_ _host_
   _node_
 
   *Arguments and Values:*
@@ -384,8 +385,8 @@
 
   *Class Precedence List:*
 
-  {timeout}, {error}, {serious‑condition}, {condition},
-  {standard‑object}, {t}
+  {timeout}, {error}, {serious-condition}, {condition},
+  {standard-object}, {t}
 
   *Description:*
 

commit 767c03b9d8414351236c13d08849e96bfda98713
Author: Max Rottenkolber <max@mr.gy>
Date:   Tue Sep 27 23:12:36 2016 +0200

    software/erlangen/api: minor changes.

diff --git a/software/erlangen/api.mk2 b/software/erlangen/api.mk2
index 09e45fa..6385232 100644
--- a/software/erlangen/api.mk2
+++ b/software/erlangen/api.mk2
@@ -1,13 +1,13 @@
-< erlangen
+< erlangen \(Package\)
 
- Distributed asychronous message passing system for Clozure Common Lisp.
+ Distributed, asychronous message passing system for Clozure Common Lisp.
 
 
  < \*agent‑debug\* \(Variable\)
 
   *Initial Value:*
 
-  {T}
+  {NIL}
 
   *Description:*
 
@@ -116,7 +116,7 @@
 
   *Exceptional Situations:*
 
-  If _agent_ is not the _calling agent_ and the _kill message_ could not
+  If _agent_ is not the _calling agent_, and the _kill message_ could not
   be delivered successfully an _error_ of _type_ {send-error} is
   signaled.
 
@@ -143,10 +143,10 @@
   When the _calling agent_ exits it will attempt to kill _agent_ with the
   _exit reason_ of the _calling agent_.
 
-  When _agent_ exits and _mode_ is {:link} it will attempt to kill
+  When _agent_ exits, and _mode_ is {:link} it will attempt to kill the
   _calling agent_ with the _exit reason_ of _agent_.
 
-  When _agent_ exits and _mode_ is {:monitor} it will attempt to send an
+  When _agent_ exits, and _mode_ is {:monitor} it will attempt to send an
   _exit notification_ to the _calling agent_.
 
   An _exit notification_ is of the form
@@ -159,12 +159,14 @@
 
   {\(} _status_ {.} _values_ {\)}
 
-  A _status_ of {:ok} means that the _agent_ exited normally and _values_
-  will be a list of its _return values_.
+  _status_::= {:ok}\|{:exit}
 
-  A _status_ of {:exit} means that the _agent_ was either killed by
+  The _status_ {:ok} indicates that the _agent_ exited normally, and
+  _values_ will be a list of its _return values_.
+
+  The _status_ {:exit} indicates that the _agent_ was either killed by
   {exit} or aborted because of an unhandled _condition_ of _type_
-  {serious-condition} and _values_ will be the _reason_ supplied to
+  {serious-condition}, and _values_ will be the _reason_ supplied to
   {exit} or the _condition object_.
 
   The attempts to kill or notify _linked agents_ will fail if the

commit 8ce28d19e58d175f9ff0aea665acb6142f9d76b7
Author: Max Rottenkolber <max@mr.gy>
Date:   Fri Sep 23 03:51:46 2016 +0200

    Add software/erlangen/api.{meta,mk2}

diff --git a/software/erlangen/api.meta b/software/erlangen/api.meta
new file mode 100644
index 0000000..fc8a83b
--- /dev/null
+++ b/software/erlangen/api.meta
@@ -0,0 +1,4 @@
+:document (:title "Erlangen API Documentation")
+:source (:system :erlangen
+         :api-document (:erlangen))
+:stylesheets ((:media "screen" :href "/site-assets/api.css"))
diff --git a/software/erlangen/api.mk2 b/software/erlangen/api.mk2
new file mode 100644
index 0000000..09e45fa
--- /dev/null
+++ b/software/erlangen/api.mk2
@@ -0,0 +1,441 @@
+< erlangen
+
+ Distributed asychronous message passing system for Clozure Common Lisp.
+
+
+ < \*agent‑debug\* \(Variable\)
+
+  *Initial Value:*
+
+  {T}
+
+  *Description:*
+
+  If {\*agent-debug\*} is _true_ when calling {spawn}, _conditions_ of
+  _type_ {serious-condition} will not be automatically handled for the
+  spawned _agent_. The debugger will be entered so that the call stack
+  can be inspected. Invoking the {exit} _restart_ will resume normal
+  operation except that the exit reason will be the _agent_ instead of
+  the fatal _condition_.
+
+ >
+
+
+ < \*default‑mailbox‑size\* \(Variable\)
+
+  *Initial Value:*
+
+  {64}
+
+  *Description:*
+
+  {\*default-mailbox-size\*} is the default value of the {:mailbox-size}
+  parameter to {spawn}.
+
+ >
+
+
+ < agent \(Function\)
+
+  *Syntax:*
+
+  — Function: *agent* _\<no arguments\>_
+
+  *Description:*
+
+  {agent} returns the _calling agent_.
+
+ >
+
+
+ < agent \(Type\)
+
+  *Syntax:*
+
+  _agent_::= _structure_ \| _keyword_ \| _string_
+
+  *Description:*
+
+  An _agent_ can either be an _agent structure_, a _keyword_ denoting a
+  registered _agent_ or a _string_ denoting a _remote agent_.
+
+  A _remote agent_ is denoted by a _string_ of the form
+  {"}_host_{/}_node_{/}_agent_{"} where _host_ is the host name, _node_
+  is the _node name_ and _agent_ is the _agent identifier_ of the _remote
+  agent_.
+
+  An _agent identifier_ is either a hexadecimal digit string denoting an
+  _anonymous agent_ or a colon followed by a _symbol name_ denoting a
+  _registered agent_. In the latter case, the _symbol name_ may not
+  contain the slash \({/}\) character.
+
+  *Notes:*
+
+  Only _agent structures_ are of _type_ {agent}.
+
+ >
+
+
+ < call \(Type\)
+
+  *Syntax:*
+
+  _call_::= {\(}_function_ _argument_\*{\)}
+
+  *Arguments and Values:*
+
+  _function_—a _symbol_ denoting a _function_.
+
+  _argument_—a _serializable object_.
+
+  *Description:*
+
+  A _call_ denotes a portable function call to be invoked on a given
+  _node_. A _call_ is a _list_ whose first element is a _symbol_ denoting
+  a _function_ and whose remaining elements are arguments to be applied
+  to the denoted _function_.
+
+ >
+
+
+ < exit \(Function\)
+
+  *Syntax:*
+
+  — Function: *exit* {&optional} _reason_ _agent_
+
+  *Arguments and Values:*
+
+  _reason_—an _object_.
+
+  _agent_—an _agent_. Default is the _calling agent_.
+
+  *Description*:
+
+  {exit} kills _agent_ with _reason_ as the _exit reason_ of _agent_.
+
+  *Exceptional Situations:*
+
+  If _agent_ is not the _calling agent_ and the _kill message_ could not
+  be delivered successfully an _error_ of _type_ {send-error} is
+  signaled.
+
+ >
+
+
+ < link \(Function\)
+
+  *Syntax:*
+
+  — Function: *link* _agent_ {&optional} _mode_
+
+  *Arguments and Values:*
+
+  _agent_—an _agent_.
+
+  _mode_—a _keyword_. Either {:link} or {:monitor}. Defaults to {:link}.
+
+  *Description*:
+
+  {link} _links_ the _calling agent_ to _agent_. After two _agents_ are
+  _linked_ they behave as follows:
+
+  When the _calling agent_ exits it will attempt to kill _agent_ with the
+  _exit reason_ of the _calling agent_.
+
+  When _agent_ exits and _mode_ is {:link} it will attempt to kill
+  _calling agent_ with the _exit reason_ of _agent_.
+
+  When _agent_ exits and _mode_ is {:monitor} it will attempt to send an
+  _exit notification_ to the _calling agent_.
+
+  An _exit notification_ is of the form
+
+  {\(} _agent_ {.} _exit-reason_ {\)}
+
+  where _exit-reason_ is the _exit reason_ of _agent_.
+
+  An _exit reason_ has the following from:
+
+  {\(} _status_ {.} _values_ {\)}
+
+  A _status_ of {:ok} means that the _agent_ exited normally and _values_
+  will be a list of its _return values_.
+
+  A _status_ of {:exit} means that the _agent_ was either killed by
+  {exit} or aborted because of an unhandled _condition_ of _type_
+  {serious-condition} and _values_ will be the _reason_ supplied to
+  {exit} or the _condition object_.
+
+  The attempts to kill or notify _linked agents_ will fail if the
+  respective message can not be delivered to the target _agent_. Any
+  error conditions that arise due to the failure will be silently
+  ignored.
+
+  *Exceptional Situations:*
+
+  If _agent_ is the _calling agent_ an _error_ of _type_ {simple-error}
+  is signaled.
+
+ >
+
+
+ < node \(Function\)
+
+  *Syntax:*
+
+  — Function: *node* {&key} _host_ _name_
+
+  *Arguments and Values:*
+
+  _host_—a _string_. The default is {"localhost"}.
+
+  _name_—a _string_. The default is a unique name.
+
+  *Description:*
+
+  {node} spawns the node protocol server to listen on a random free port
+  of _host_. It then registers its _name_ and listening port with the
+  port mapper. Once the node is registered, it is capable of
+  communicating with remote nodes.
+
+  *Examples:*
+
+  #code#
+;; Start talking to remote nodes:
+(spawn '(node))
+  #
+
+ >
+
+
+ < receive \(Function\)
+
+  *Syntax:*
+
+  — Function: *receive* {&key} _timeout_ _poll‑interval_
+
+  *Arguments and Values:*
+
+  _timeout_, _poll-interval_—positive _numbers_.
+
+  *Description*:
+
+  {receive} returns the next message for the _calling agent_. If the
+  _mailbox_ of the _calling agent_ is empty, {receive} will block until a
+  message arrives.
+
+  If _timeout_ is supplied {receive} will block for at most _timeout_
+  seconds and poll for a message every _poll-interval_ seconds.
+
+  *Exceptional Situations:*
+
+  If the _calling agent_ was killed by another _agent_ by use of {exit} a
+  _serious-condition_ of _type_ {exit} is signaled.
+
+  If _timeout_ is supplied and exceeded an _error_ of _type_ {timeout} is
+  signaled.
+
+ >
+
+
+ < register \(Function\)
+
+  *Syntax:*
+
+  — Function: *register* _name_ {&optional} _agent_
+
+  *Arguments and Values:*
+
+  _name_—a _keyword_.
+
+  _agent_—an _agent_. Default is the _calling agent_.
+
+  *Description*:
+
+  {register} associates _name_ with _agent_.
+
+  *Exceptional Situations:*
+
+  If _name_ is already associated with an _agent_ an _error_ of _type_
+  {simple-error} is signaled.
+
+ >
+
+
+ < registered \(Function\)
+
+  *Syntax:*
+
+  — Function: *registered* _\<no arguments\>_
+
+  *Description*:
+
+  {registered} returns a _list_ of names associated with _agents_.
+
+ >
+
+
+ < select \(Macro\)
+
+  *Syntax:*
+
+  — Macro: *select* {&rest} _clauses_
+
+  _clauses_::= _normal-clause_\* \[_receive-clause_\]
+
+  _normal-clause_::= {\(}_poll-form_ _vars_ _body-form_\*{\)}
+
+  _receive-clause_::= {\(:receive} _vars_ _body-form_\*{\)}
+
+  *Arguments and Values:*
+
+  _poll-form_, _body-form_—_forms_.
+
+  _vars_—a _list_ of _symbols_.
+
+  *Description:*
+
+  {select} repeatedly calls the _poll-forms_ of each _normal-clause_ \(in
+  order\) until a _poll-form_ returns a non-nil value as its first result
+  and _vars_ is non-nil. It then evaluates each _body-form_ of the
+  respective _normal-clause_ with the return values of its _poll-forms_
+  bound to _vars_ and returns their result.
+
+  If a _receive-clause_ is supplied and its _vars_ are non-nil, {select}
+  will evaluate each _body-form_ of the clause with the received message
+  bound to the first _symbol_ in _vars_ and return their result. If no
+  _receive-clause_ is supplied, {select} will silently discard incoming
+  messages.
+
+ >
+
+
+ < send \(Function\)
+
+  *Syntax:*
+
+  — Function: *send* _message_ _agent_
+
+  *Arguments and Values:*
+
+  _message_—an _object_.
+
+  _agent_—an _agent_.
+
+  *Description*:
+
+  {send} delivers _message_ to _agent_.
+
+  *Exceptional Situations:*
+
+  If _message_ could not be delivered successfully an _error_ of _type_
+  {send-error} is signaled.
+
+ >
+
+
+ < send‑error \(Condition Type\)
+
+  *Class Precedence List:*
+
+  {send‑error}, {error}, {serious‑condition}, {condition},
+  {standard‑object}, {t}
+
+  *Description:*
+
+  Describes an error condition that can occur when calling {send}. It
+  denotes a that {send} was unable to successfully deliver the message to
+  the recepient.
+
+ >
+
+
+ < spawn \(Function\)
+
+  *Syntax:*
+
+  — Function: *spawn* _function_ {&key} _attach_ _mailbox‑size_ _host_
+  _node_
+
+  *Arguments and Values:*
+
+  _function_—a _function designator_ or a _call_.
+
+  _attach_—a _keyword_ or {nil}.
+
+  _mailbox-size_—a positive _unsigned integer_. The default is
+  {\*default-mailbox-size\*}.
+
+  *Description:*
+
+  {spawn} starts and returns a new _agent_ with a mailbox capacity of
+  _mailbox-size_. If _attach_ is {:link} or {:monitor} the _calling
+  agent_ will be linked to the new _agent_ as if by {link} but before the
+  _agent_ is started. Once the _agent_ is started it will execute
+  _function_.
+
+ >
+
+
+ < timeout \(Condition Type\)
+
+  *Class Precedence List:*
+
+  {timeout}, {error}, {serious‑condition}, {condition},
+  {standard‑object}, {t}
+
+  *Description:*
+
+  Describes an error condition that can occur when using functions with a
+  timeout. It denotes a that the operations was unable to successfully
+  complete within a given deadline.
+
+ >
+
+
+ < unlink \(Function\)
+
+  *Syntax:*
+
+  — Function: *unlink* _agent_
+
+  *Arguments and Values:*
+
+  _agent_—an _agent_.
+
+  *Description:*
+
+  {unlink} removes any _link_ between _agent_ and the _calling agent_.
+
+  *Exceptional Situations:*
+
+  If _agent_ is the _calling agent_ an _error_ of _type_ {simple-error}
+  is signaled.
+
+ >
+
+
+ < unregister \(Function\)
+
+  *Syntax:*
+
+  — Function: *unregister* _name_
+
+  *Arguments and Values:*
+
+  _name_—a _keyword_.
+
+  *Description*:
+
+  {unregister} removes the registered _name_, associated with an _agent_.
+
+  *Exceptional Situations:*
+
+  If the _name_ is not associated with an _agent_ an _error_ of _type_
+  {simple-error} is signaled.
+
+ >
+
+>
+