[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/05 05:31:02

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

Log message:
        More about functional

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/fenfire/fenfire/docs/pegboard/functional_futureproof_api--tjl/peg.rst.diff?tr1=1.1&tr2=1.2&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.1 
fenfire/docs/pegboard/functional_futureproof_api--tjl/peg.rst:1.2
--- fenfire/docs/pegboard/functional_futureproof_api--tjl/peg.rst:1.1   Wed Sep 
 3 07:19:15 2003
+++ fenfire/docs/pegboard/functional_futureproof_api--tjl/peg.rst       Fri Sep 
 5 05:31:01 2003
@@ -3,8 +3,8 @@
 =============================================================
 
 :Author:   Tuomas J. Lukka
-:Last-Modified: $Date: 2003/09/03 11:19:15 $
-:Revision: $Revision: 1.1 $
+:Last-Modified: $Date: 2003/09/05 09:31:01 $
+:Revision: $Revision: 1.2 $
 :Status:   Incomplete
 
 Functions and caching are here to stay with us. 
@@ -18,11 +18,74 @@
 Issues
 ======
 
+- How do we specify which functions need to be run in the OpenGL thread?
+  How general should we make this ability?
+
+  One important point is that this is a property of the **function**, not
+  its instantiation.
+
+  The reasonable alternatives, given this, are 
+  
+  1) to have separate interfaces
+     for the per-function properties and for the ``Function`` 
+     to implement them.
+
+     Pros:
+       - simple
+     Cons:
+       - profusion of interfaces
+
+  2) to add, in the ``Functional`` api a Hints object and "getHints"
+     or something
+
+     Pros:
+       - flexible
+     Cons:
+       - slightly klunky
+
+  RESOLUTION: 2). this is pretty much as good as we can get. If the Hints
+  object is specified flexibly, can be done without loss of generality
+  (i.e. can give Id to specific sets of Background objects).
+
+
+
 - How should we give hints to the Functional API about which functions
   are slow?
 
-- How do we specify which functions need to be run in the OpenGL thread?
-  How general should we make this ability?
+  This may be a property of the function, or a property of the instance.
+
+  RESOLUTION: For now, allow only as part of Hints.
+
+
+- Do we want/need to specify that a function uses its parameter functions once,
+  maybe once, several times?
+
+  RESOLUTION: Not yet. So far, no use for such information has been given.
+
+- Do we want/need to specify that a function uses its parameter functions 
+  always with the same parameter that it gets?
+
+  RESOLUTION: Not yet. So far, no use for such information has been given.
+
+- What about slow tasks that want to use OpenGL, such as Mipzip generation?
+  Paper generation is much faster.
+
+  RESOLUTION: Nothing for now - they should be run in a thread, and start
+  new processes. This is even slower, but OTOH will crash less likely
+  (there has been some stability problems when generating lots of mipzips
+  that seem like a problem in zlib or NVIDIA drivers ((yeah, right ;))).
+
+- Should we try to do more through reflection, reading parameters &c
+  from finished objects? We might be able to map::
+
+    Function node1 = new G("X");
+    Function node2 = new F("X", node1);
+
+  to the Functional objects?
+
+  RESOLUTION: Not yet. We can always create a new tag interface for 
``Function``
+  objects that obey the special restrictions associated with that,
+  if any are needed.
 
 Changes
 =======
@@ -67,7 +130,32 @@
 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
+------------------
+
     interface Functional {
+       /** Hints about a Function class.
+        * Created using HintsMaker.
+        * An empty interface in order to be unmodifiable.
+        */
+       interface Hints {
+       }
+       /** An interface for creating Hints objects.
+        */
+       interface HintsMaker {
+           /** This function must be run in a background object
+            * of the given group if it's not run directly.
+            * This is useful for using Libvob OpenGL, since 
+            * OpenGL objects should only be handled in one thread.
+            */
+           void setBackgroundGroup(Object id);
+           /**
+           void setSlow(boolean isSlow);
+           /** Create the Hints object.
+            */
+           Hints make();
+       }
+
        /** A node in the functional calculation DAG.
         */
        interface Node {
@@ -91,3 +179,56 @@
            Object[] parameters
            );
     }
+
+Example about using the API
+---------------------------
+
+First, define two functions::
+
+    public class G implements PureFunction {
+    
+       public G(Object bla) {
+       }
+       public Object f(Object o) {
+           ...
+       }
+    }
+
+    public class F implements PureFunction {
+       static public Functional.Hints functionalHints;
+       static {
+           // F needs to be run in the OpenGL thread
+           Functional.HintsMaker maker = 
+               new Functional.HintsMaker();
+           maker.setBackgroundGroup("OPENGL");
+           functionalHints = maker.make();
+       }
+    
+       public F(Object bla, Function g) {
+       }
+       public Object f(Object o) {
+           ...
+       }
+    }
+
+And construction the functions::
+
+    Functional.Node node1 = Functional.createNode(
+       "N1",
+       G.class, 
+       new Object[] {"X"});
+    Functional.Node node2 = Functional.createNode(
+       "N2",
+       F.class,
+       new Object[] {"Y", node1});
+
+This constructor is "equivalent" to::
+
+    Function node1 = new G("X");
+    Function node2 = new F("X", node1);
+
+except that the result may be cached.
+
+
+
+