[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/07 12:23:22

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

Log message:
        More to the PEG

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/fenfire/fenfire/docs/pegboard/functional_futureproof_api--tjl/peg.rst.diff?tr1=1.4&tr2=1.5&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.4 
fenfire/docs/pegboard/functional_futureproof_api--tjl/peg.rst:1.5
--- fenfire/docs/pegboard/functional_futureproof_api--tjl/peg.rst:1.4   Fri Sep 
 5 09:22:02 2003
+++ fenfire/docs/pegboard/functional_futureproof_api--tjl/peg.rst       Sun Sep 
 7 12:23:22 2003
@@ -3,14 +3,15 @@
 =============================================================
 
 :Author:   Tuomas J. Lukka
-:Last-Modified: $Date: 2003/09/05 13:22:02 $
-:Revision: $Revision: 1.4 $
+:Last-Modified: $Date: 2003/09/07 16:23:22 $
+:Revision: $Revision: 1.5 $
 :Status:   Incomplete
 
 Functions and caching are here to stay with us. 
 However, the caching is currently pretty nasty for the programmer
 and requires active thinking, especially in the case of super-lazy
-functions.
+functions (i.e. caches that schedule evaluation only after being
+requested the value and return a placeholder).
 
 This PEG provides a future-proof API for handling functions and caching
 cleanly.
@@ -93,11 +94,81 @@
   RESOLUTION: For now, only function level. Hints object will have a 
setPlaceholder
   call.
 
+- Should the Functional API know about NodeFunctions and especially about Swamp
+  and observable graphs?
 
+  It would be nice to be clean but OTOH it would be difficult.
+
+  RESOLUTION: For now, Functional will require Swamp. We'll look for a way
+  to disentangle them once we have more experience with different 
implementations
+  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?
+  Who is aware of the ConstGraph to be used?
+
+  RESOLUTION: The Functional API contains the ConstGraph itself and creates
+  Function wrappers for NodeFunctions.
+
+  This may need to be changed later, once we are juggling several graphs 
+  at the same time.
+
+Introduction
+============
+
+The point of this PEG is to allow for transparent lazy and super-lazy caching
+of functions, with (in the future) automatic adjustment of cache locations and 
sizes
+based on actual run-time information. This means that more information about
+functions, and parameter functions is required.
+
+This PEG defines a way of creating functions that gives the API maximum 
information
+about the functional structure so created, to allow all these.
+
+As an important example of why this API is needed, consider the NodeFunctions 
in FenPDF  
+that provide the Canvas2D with the Placeables for each node.
+The functions could be written as ::
+
+    f(x) = Multiplex( Wrap( PageNodeFunc(x), 1 ), TextNodeFunc(x) )
+    g(x) = Multiplex( Wrap( PageNodeFunc(x), 2 ), TextNodeFunc(x) )
+
+The problem is that we want to
+
+1) Cache the result of f(x) and g(x) normally
+
+2) Cache the result of PageNodeFunc(x) super-lazily as it is slower to run.
+
+We do *not* want to cache TextNodeFunc super-lazily, since it is quite fast to 
run.
+However, to allow the last-used nodes to be calculated first, we want to use a 
LIFO
+(last-in-first-out) computation for the nodes. However, if the placeholder
+from the super-lazily cached PageNodeFunc is retrieved from the cache of the 
Multiplex
+function, the super-lazy cache's last-used date will remain wrong.
+
+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.
 
 Changes
 =======
 
+Creating functions
+------------------
+
+Functions shall no more be created directly by calling the constructor
+(it's allowed but will not be cacheable &c).
+Instead, a reflective Function creation API shall be used.
+
+This is vital to get the information about the functions to the API
+to allow proper caching.
+
+New package
+-----------
+
+Create the package ``org.fenfire.functional`` and move all ``Function`` 
+and ``NodeFunction`` -related classes there. Naturally, classes
+such as ``VobWrapperFunction`` that only **use** or **implement** 
+the API shall remain.
+
+The Cache classes shall also be moved to Functional and be deprecated.
+
 GL- and nonGLfunctions
 ----------------------
 
@@ -130,24 +201,27 @@
 to schedule its calculation in a background thread and throw an exception. 
That way,
 the OpenGL thread is free for other operations during the calculation.
 
-This allows us to emulate some sort of continuation mechanism for Java.
+This allows the function evaluation to stop at the first uncached value that 
is encountered.
 
-Creating functions
+The Functional API
 ------------------
 
-Functions shall no more be created directly (it's allowed but will not be 
cacheable &c).
-Instead, a reflective Function creation API shall be used:
+::
 
-The Functional API
-------------------
+    package org.fenfire.functional;
 
     interface Functional {
+
        /** Hints about a Function class.
         * Created using HintsMaker.
         * An empty interface in order to be unmodifiable.
+        * Each class that implements ``Function`` or ``NodeFunction``
+        * that is given to this API shall have a static member 
``functionalHints``
+        * of this type.
         */
        interface Hints {
        }
+
        /** An interface for creating Hints objects.
         */
        class HintsMaker {
@@ -185,6 +259,7 @@
             */
            Function getCallableFunction();
        }
+
        /** Create a new node in the DAG.
         * @param id An identifier for the node. Used for determining caching 
&c.
         *           Should be stable between invocations.
@@ -202,8 +277,8 @@
            );
     }
 
-Example about using the API
----------------------------
+Example: using the API
+----------------------
 
 First, define two functions::