Changeset 426 for branches/thune/thread_safe/doc/UserManual

Timestamp:

07/05/07 04:03:51 (17 months ago)

Author:

krobillard

Message:

Added component! & lit-select! datatypes.
ur_makeBlockT() now has a ptr return argument.

Files:

• branches/thune/thread_safe/doc/UserManual (modified) (8 diffs)

branches/thune/thread_safe/doc/UserManual

@@ -88 +88 @@
 select!      obj/x my-block/2
 set-select!  :obj/x :my-block/2
+lit-select!  'obj/x 'my-block/2
 slice!
 time!        10:02 -0:0:32.08
 context!
+component!
 ===========  ==========
 
@@ -102 +104 @@
 
 Macros can be used wherever a constant is needed to improve evaluation
-speed.
+speed.  They are also useful for conditional code generation.
 
 Example::
@@ -110 +112 @@
     box-width <border> add
 
+Conditional Example::
+
+    <script-env/os [
+        linux   ["Linux"]
+        solaris ["Solaris"]
+        ["Unsupported OS" error]
+     ] case>
+    print
 
 Currently, macro! values cannot be created by the user.
@@ -243 +253 @@
 .. The Evaluator
    Contexts & Binding
+
+
+Components
+----------
+
+Components are similar to functions, but they operate via a dataflow model.
+They have inputs, outputs which are connected to the inputs of other
+components, and a body which is evaluated when all inputs are set.
+
+Components must have at least one input, but they don't require any outputs.
+
+Here is an example of how to create and connect components::
+
+    [a b -- out] [a b mul :out] component :c1
+    [val] [val .] component :probe
+    'c1/out 'probe/val connect
+
+Now, when the inputs to *c1* are set, *probe* will automatically be invoked::
+
+    3 :c1/a
+    5 :c1/b
+    15
+
+Further changes to the inputs will continue to invoke the *probe* component::
+
+    5 :c1/a
+    25
+
+*Connect* also accepts components as arguments.  This is short-hand for
+refering to the first input or output.
+The following call makes the same connection as the example above::
+
+    c1 probe connect
 
 
@@ -533 +576 @@
 ::
 
-        (logic -- )
+    (logic -- )
 
 Evaluate next value if TOS is true.  To evaluate more than one value use
@@ -558 +601 @@
 ::
 
-        (ser new [part int!] -- ser)
+    (ser new [part int!] -- ser)
 
 Change series at current position.
@@ -568 +611 @@
 ::
 
-        (ser pat -- end series!/none!)
+    (ser pat -- end series!/none!)
 
 Move position to end of matching pattern.
@@ -584 +627 @@
 
 
+Extending The System
+====================
+
+Adding C Functions
+------------------
+
+C functions are defined with the *UR_CALL* macro.
+
+The function is responsible for checking that arguments are of the correct
+type and for reporting any errors.  If type checking were built into the
+evaluator there would be redundant checks for the typical case where the
+function accepts multiple types for a given argument or pattern of
+arguments.
+
+Always access and check stack arguments starting with *tos* and work down.
+Since the bottom of the stack contains *UT_UNSET*, checking in this order
+avoids an extra check to make sure that the stack holds at least the number
+of expected arguments.
+
+