[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[ff-cvs] fenfire/docs/pegboard/functional_futureproof_ap...
From: |
Tuomas J. Lukka |
Subject: |
[ff-cvs] fenfire/docs/pegboard/functional_futureproof_ap... |
Date: |
Sun, 07 Sep 2003 12:23:23 -0400 |
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::
- [ff-cvs] fenfire/docs/pegboard/functional_futureproof_ap..., Tuomas J. Lukka, 2003/09/05
- [ff-cvs] fenfire/docs/pegboard/functional_futureproof_ap..., Tuomas J. Lukka, 2003/09/05
- [ff-cvs] fenfire/docs/pegboard/functional_futureproof_ap...,
Tuomas J. Lukka <=
- [ff-cvs] fenfire/docs/pegboard/functional_futureproof_ap..., Tuomas J. Lukka, 2003/09/08
- [ff-cvs] fenfire/docs/pegboard/functional_futureproof_ap..., Tuomas J. Lukka, 2003/09/08
- [ff-cvs] fenfire/docs/pegboard/functional_futureproof_ap..., Tuomas J. Lukka, 2003/09/08
- [ff-cvs] fenfire/docs/pegboard/functional_futureproof_ap..., Tuomas J. Lukka, 2003/09/09