More documentation on the on-going change of the output storage contract

NEWS.txt

@@ -3,6 +3,31 @@ Modifications in the trunk since the last release
 Theano 0.4.0rc4 (2011-06-13)
 --------------------------------------------------
 
+Change in output memory storage for Ops:
+ If you implemented custom Ops, with either C or Python implementation,
+ this will concern you.
+
+ The contract for memory storage of Ops has been changed. In particular,
+ it is no longer guaranteed that output memory buffers are either empty,
+ or allocated by a previous execution of the same Op.
+
+ Right now, here is the situation:
+ * For Python implementation (perform), what is inside output_storage
+   may have been allocated from outside the perform() function, for
+   instance by another node (e.g., Scan) or the Mode. If that was the
+   case, the memory can be assumed to be C-contiguous (for the moment).
+ * For C implementations (c_code), nothing has changed yet.
+
+ In a future version, the content of the output storage, both for Python and C
+ versions, will either be NULL, or have the following guarantees:
+ * It will be a Python object of the appropriate Type (for a Tensor variable,
+   a numpy.ndarray, for a GPU variable, a CudaNdarray, for instance)
+ * It will have the correct number of dimensions, and correct dtype
+ However, its shape and memory layout (strides) will not be guaranteed.
+
+ When that change is made, the config flag DebugMode.check_preallocated_output
+ will help you find implementations that are not up-to-date.
+
 Deprecation:
  * tag.shape attribute deprecated (#633)
  * CudaNdarray_new_null is deprecated in favour of CudaNdarray_New

doc/sandbox/ccodegen.txt

@@ -29,6 +29,11 @@ List of methods in ResultBase:
 
 '''c_cleanup:''' This method should clean up all the variables declared by c_declare.
 
+.. warning::
+
+    This page describes usage of c_init and c_extract as of version 0.4.0 (and
+    previous versions). This will change in the future, to allow c_code to
+    use preallocated memory buffers of the outputs.
 
 Important notes:
   * ''Either'' c_init or c_extract will be called. The former for temporary variables and outputs, the latter for inputs. If the former is used, py_<name> will be set to Py_None regardless of what is in storage_<name>.

theano/gof/op.py

@@ -193,14 +193,17 @@ class CLinkerOp(CLinkerObject):
            There is a string for each input of the function, and the string is the name of a C
            `PyObject` variable pointing to that input.
          `outputs` : list of strings
-           Each string is the name of a `PyObject` pointer where the Op should store its
-           variables.  This pointer could be NULL, or contain an object of the right
-           Type (in the Theano sense) to store the output of the computation.
-           For instance, for a TensorVariable, it will be a Numpy ndarray with
-           the right number of dimensions, and the right dtype. However, its
-           shape, or stride pattern, could not be adequate.
-           It could be unchanged from the end of the previous execution, or allocated
-           by another Op, or by the Mode.
+           Each string is the name of a `PyObject` pointer where the Op should
+           store its variables.  As of version 0.4.0, this pointer could be
+           NULL, or contain an object allocated during a previous call to the
+           same function, unchanged from the end of the previous execution.
+           In a future version, there will be no guarantee on where that
+           object will be created (it could be allocated during a previous
+           execution, or by another Op, by the Mode, etc.). It will still
+           be of an appropriate Type (in the Theano sense) to store the output
+           of the computation: for instance, for a TensorVariable, it will be a
+           Numpy ndarray with the right number of dimensions, and the right dtype.
+           However, its shape, or stride pattern, could not be adequate.
          `sub` : dict of strings
            extra symbols defined in `CLinker` sub symbols (such as 'fail').
            WRITEME