[Bf-blender-cvs] [24483122786] functions: comment on tuple-call

[Jacques Lucke]

Commit: 24483122786970afa787d120dde69d31a361cd93
Author: Jacques Lucke
Date:   Wed Jul 3 15:01:54 2019 +0200
Branches: functions
https://developer.blender.org/rB24483122786970afa787d120dde69d31a361cd93

comment on tuple-call

===================================================================

M	source/blender/functions/backends/tuple_call/execution_context.hpp
M	source/blender/functions/backends/tuple_call/lazy_to_normal.cpp
M	source/blender/functions/backends/tuple_call/tuple_call.hpp

===================================================================

diff --git a/source/blender/functions/backends/tuple_call/execution_context.hpp b/source/blender/functions/backends/tuple_call/execution_context.hpp
index 4df493a772b..c59e193caf4 100644
--- a/source/blender/functions/backends/tuple_call/execution_context.hpp
+++ b/source/blender/functions/backends/tuple_call/execution_context.hpp
@@ -1,5 +1,16 @@
 #pragma once
 
+/**
+ * When a function is executed using the tuple-call backend, there is always an execution context.
+ * The context contains information about the current call stack. This information is important to
+ * produce good error messages. The call stack of tuple-call functions can be very different from
+ * the actual C/C++ call stack. Therefore it is handled separately.
+ *
+ * Obviously, setting up the call stack should be very efficient, since might be done very often
+ * when e.g. a function is called for every vertex of a mesh. Nevertheless, it should contain a lot
+ * of information in the case of an error.
+ */
+
 #include "FN_core.hpp"
 
 namespace FN {
diff --git a/source/blender/functions/backends/tuple_call/lazy_to_normal.cpp b/source/blender/functions/backends/tuple_call/lazy_to_normal.cpp
index c4c4de97ef2..ee6550243f4 100644
--- a/source/blender/functions/backends/tuple_call/lazy_to_normal.cpp
+++ b/source/blender/functions/backends/tuple_call/lazy_to_normal.cpp
@@ -3,6 +3,10 @@
 
 namespace FN {
 
+/**
+ * This just turns a lazy tuple-call body into a normal one by calling it multiple times, until it
+ * is done.
+ */
 class MakeEagerBody : public TupleCallBody {
  private:
   LazyInTupleCallBody *m_lazy_body;
diff --git a/source/blender/functions/backends/tuple_call/tuple_call.hpp b/source/blender/functions/backends/tuple_call/tuple_call.hpp
index 912f46ac3ff..2d347efc671 100644
--- a/source/blender/functions/backends/tuple_call/tuple_call.hpp
+++ b/source/blender/functions/backends/tuple_call/tuple_call.hpp
@@ -1,5 +1,11 @@
 #pragma once
 
+/**
+ * The tuple-call calling convention is the main type of function bodies for the pure C++ backend
+ * (without JIT compilation). A function implementing the tuple-call body takes a tuple as input
+ * and outputs a tuple containing the computed values.
+ */
+
 #include "FN_tuple.hpp"
 #include "execution_context.hpp"
 
@@ -18,11 +24,17 @@ class TupleCallBodyBase : public FunctionBody {
 
   virtual void init_defaults(Tuple &fn_in) const;
 
+  /**
+   * Get the metadata for tuples that this function can take as input.
+   */
   SharedTupleMeta &meta_in()
   {
     return m_meta_in;
   }
 
+  /**
+   * Get the metadata for tuples that this function can output.
+   */
   SharedTupleMeta &meta_out()
   {
     return m_meta_out;
@@ -33,6 +45,9 @@ class TupleCallBody : public TupleCallBodyBase {
  public:
   BLI_COMPOSITION_DECLARATION(TupleCallBody);
 
+  /**
+   * Calls the function with additional stack frames.
+   */
   inline void call__setup_stack(Tuple &fn_in, Tuple &fn_out, ExecutionContext &ctx) const
   {
     TextStackFrame frame(this->owner()->name().data());
@@ -67,6 +82,19 @@ class TupleCallBody : public TupleCallBodyBase {
     this->call__setup_stack(fn_in, fn_out, ctx);
   }
 
+  /**
+   * This function has to be implemented for every tuple-call body. It takes in two references to
+   * different tuples and the current execution context.
+   *
+   * By convention, when the function is called, the ownership of the data in both tuples is this
+   * function. That means, that values from fn_in can also be destroyed or relocated if
+   * appropriate. If fn_in still contains initialized values when this function ends, they will be
+   * destructed.
+   *
+   * The output tuple fn_out can already contain data beforehand, but can also contain only
+   * uninitialized data. When this function ends, it is expected that every element in fn_out is
+   * initialized.
+   */
   virtual void call(Tuple &fn_in, Tuple &fn_out, ExecutionContext &ctx) const = 0;
 };
 
@@ -119,12 +147,34 @@ class LazyState {
   }
 };
 
+/**
+ * Similar to the normal tuple-call body, but supports lazy input evaluation. That means, that not
+ * all its input have to be computed before it is executed. The call function can request which
+ * inputs it needs by e.g. first checking other elements in fn_in.
+ *
+ * To avoid recomputing the same temporary data multiple times, the function can get a memory
+ * buffer of a custom size to store custom data until it is done.
+ */
 class LazyInTupleCallBody : public TupleCallBodyBase {
  public:
   BLI_COMPOSITION_DECLARATION(LazyInTupleCallBody);
 
+  /**
+   * Required buffer size for temporary data.
+   */
   virtual uint user_data_size() const;
+
+  /**
+   * Indices of function inputs that are required in any case. Those elements can be expected to be
+   * initialized when call is called for the first time.
+   */
   virtual const SmallVector<uint> &always_required() const;
+
+  /**
+   * The ownership semantics are the same as in the normal tuple-call. The only difference is the
+   * additional LazyState parameter. With it, other inputs can be requested or the execution of the
+   * function can be marked as done.
+   */
   virtual void call(Tuple &fn_in,
                     Tuple &fn_out,
                     ExecutionContext &ctx,
@@ -165,6 +215,9 @@ class LazyInTupleCallBody : public TupleCallBodyBase {
 
 } /* namespace FN */
 
+/**
+ * Allocate input and output tuples for a particular tuple-call body.
+ */
 #define FN_TUPLE_CALL_ALLOC_TUPLES(body, name_in, name_out) \
   FN_TUPLE_STACK_ALLOC(name_in, body->meta_in().ref()); \
   FN_TUPLE_STACK_ALLOC(name_out, body->meta_out().ref());