[ff-cvs] fenfire/docs/pegboard/functional_futureproof_ap...

[Tuomas J. Lukka]

CVSROOT:        /cvsroot/fenfire
Module name:    fenfire
Branch:         
Changes by:     Tuomas J. Lukka <address@hidden>        03/09/08 04:11:55

Modified files:
        docs/pegboard/functional_futureproof_api--tjl: peg.rst 

Log message:
        Update PEG

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/fenfire/fenfire/docs/pegboard/functional_futureproof_api--tjl/peg.rst.diff?tr1=1.5&tr2=1.6&r1=text&r2=text

Patches:
Index: fenfire/docs/pegboard/functional_futureproof_api--tjl/peg.rst
diff -u fenfire/docs/pegboard/functional_futureproof_api--tjl/peg.rst:1.5 
fenfire/docs/pegboard/functional_futureproof_api--tjl/peg.rst:1.6
--- fenfire/docs/pegboard/functional_futureproof_api--tjl/peg.rst:1.5   Sun Sep 
 7 12:23:22 2003
+++ fenfire/docs/pegboard/functional_futureproof_api--tjl/peg.rst       Mon Sep 
 8 04:11:54 2003
@@ -3,8 +3,8 @@
 =============================================================
 
 :Author:   Tuomas J. Lukka
-:Last-Modified: $Date: 2003/09/07 16:23:22 $
-:Revision: $Revision: 1.5 $
+:Last-Modified: $Date: 2003/09/08 08:11:54 $
+:Revision: $Revision: 1.6 $
 :Status:   Incomplete
 
 Functions and caching are here to stay with us. 
@@ -104,7 +104,7 @@
   of ``Functional``.
 
 - How should we handle the dual Function - NodeFunction aspect in the API?
-  Single calls that handle it internally or separate calls and Node types?
+  Single calls that handle it internally or separate calls and 
FunctionalInstance types?
   Who is aware of the ConstGraph to be used?
 
   RESOLUTION: The Functional API contains the ConstGraph itself and creates
@@ -113,6 +113,14 @@
   This may need to be changed later, once we are juggling several graphs 
   at the same time.
 
+- What term should be used for the objects returned by the Functional API?
+  They correspond to instances of Functions but need their own methods.
+
+  The first idea, ``Node`` seems confusing in retrospect.
+
+  RESOLUTION: ``FunctionInstance``s. And to make it clearer, the class 
+  shall be outside the ``Functional`` class.
+
 Introduction
 ============
 
@@ -146,6 +154,24 @@
 Therefore, it is obvious that the caches need to co-operate. This API allows
 a single class to take care of all caches, so this co-operation could be 
arranged.
 
+Quick glossary
+==============
+
+This PEG depends on some concepts that have not yet been explained or published
+anywhere. Here are the definitions.
+
+Superlazy caching
+    A cache which is lazier than lazy: it does not calculate
+    the correct value for the function it is caching even when requested
+    but returns a *placeholder* value instead (such as ``null``, or an empty
+    rectangle vob or ...) and *schedules* the computation to take place
+    at a later time (when the processor would be otherwise idle).
+
+Placeholder values
+    Values that look like the real values returned from a function (i.e. are
+    of the same type) but are "blank". These values are returned by superlazy
+    caches when the true value has not yet been computed.
+
 Changes
 =======
 
@@ -210,6 +236,19 @@
 
     package org.fenfire.functional;
 
+    /** A node in the functional calculation DAG.
+     * This class represents (one, or several equivalent) instances
+     * of a class implementing Function or NodeFunction.
+     * This class wraps the computation so that the implementation
+     * of Functional is able to use more information to determine
+     * how and when to evaluate what functions.
+     */
+    interface FunctionInstance {
+       /** Get a function entry point for this node.
+        */
+       Function getCallableFunction();
+    }
+
     interface Functional {
 
        /** Hints about a Function class.
@@ -252,25 +291,18 @@
            Hints make();
        }
 
-       /** A node in the functional calculation DAG.
-        */
-       interface Node {
-           /** Get a function entry point for this node.
-            */
-           Function getCallableFunction();
-       }
-
        /** Create a new node in the DAG.
-        * @param id An identifier for the node. Used for determining caching 
&c.
+        * @param id An identifier for the node. Useful for specifying caching 
for
+        *           some particular implementations..
         *           Should be stable between invocations.
         * @param functionClass The class of which the Function (or 
NodeFunction)
         *              object should 
         *              be created.
         * @param parameters The parameters for the constructor of the class.
-        *              These may contain Node objects, which will be converted
+        *              These may contain FunctionInstance objects, which will 
be converted
         *              to functions or nodefunctions as appropriate.
         */
-       Node createNode(
+       FunctionInstance createFunctionInstance(
            Object id,
            Class functionClass,
            Object[] parameters
@@ -308,13 +340,13 @@
        }
     }
 
-And construction the functions::
+And construction the functions (``functional`` is an instance of 
``Functional``)::
 
-    Functional.Node node1 = Functional.createNode(
+    FunctionInstance node1 = functional.createFunctionInstance(
        "N1",
        G.class, 
        new Object[] {"X"});
-    Functional.Node node2 = Functional.createNode(
+    FunctionInstance node2 = functional.createFunctionInstance(
        "N2",
        F.class,
        new Object[] {"Y", node1});
@@ -324,7 +356,9 @@
     Function node1 = new G("X");
     Function node2 = new F("X", node1);
 
-except that the result may be cached.
+except that the result may be cached, since ``functional`` knows
+the complete structure and is able to deduce (or be told externally)
+what to cache.