Merge pull request #2061 from abergeron/struct_support

doc/extending/cop.txt

@@ -31,43 +31,82 @@ There are less methods to define for an Op than for a Type:
 
     .. method:: c_code(node, name, input_names, output_names, sub)
 
-      This must return C code that carries the computation we want to do.
+       This must return C code that carries the computation we want to
+       do.
 
-      sub is a dictionary of strings for you to substitute into your code.
-      It's not clear if it ever contains anything other than 'fail'.
-      sub['fail'] is a string of code that you should execute (after calling
-      PyErr_Format) if your C code needs to raise an exception.
+       `sub` is a dictionary of extras parameters to the c_code
+       method. It contains the following values:
+
+       ``sub['fail']``
+
+          A string of code that you should execute (after ensuring
+          that a python exception is set) if your C code needs to
+          raise an exception.
+
+       ``sub['struct_id']``
+
+          The integer id passed to the various _struct methods.
 
     .. method:: c_code_cleanup(node, name, input_names, output_names, sub)
 
-      This must return C code that cleans up whatever c_code allocated and
-      that we must free.
+       This must return C code that cleans up whatever c_code
+       allocated and that we must free.
 
        *Default:* The default behavior is to do nothing.
 
     .. method:: c_headers()
+
+       Returns a list of headers to include in the file. 'Python.h' is
+       included by default so you don't need to specify it.  Also all
+       of the header required by the Types involved (inputs and
+       outputs) will also be included.
+
     .. method:: c_header_dirs()
+
+       Returns a list of directories to search for headers (arguments
+       to -I).
+
     .. method:: c_libraries()
+
+       Returns a list of library names that your op needs to link to.
+       All ops are automatically linked with 'python' and the
+       libraries their types require. (arguments to -l)
+
     .. method:: c_lib_dirs()
 
-      Allows you to specify headers, libraries, and their directories,
+       Returns a list of directory to search for libraries (arguments
+       to -L).
 
     .. method:: c_compile_args()
+
+       Allows to specify additional arbitrary arguments to g++.  This
+       is not usually required.
+
     .. method:: c_no_compile_args()
 
-      Allows you to specify special g++ arguments to add/exclude
+       Returns a list of g++ arguments that are forbidden when
+       compiling this Op.
 
     .. method:: c_init_code()
 
        Allows you to specify code that will be executed once when the
-      module is initialized, before anything else is executed.
+       module is initialized, before anything else is executed.  This
+       is for code that will be executed once per Op.
 
-    .. method:: c_init_code_apply(self, node, name)
+    .. method:: c_init_code_apply(node, name)
 
        Allows you to specify code that will be executed once when the
        module is initialized, before anything else is executed and is
-      specialized for a particular apply of an :ref:`op`. Use
-      `c_init_code` if the code is the same for each apply of an op.
+       specialized for a particular apply of an :ref:`op`.
+
+    .. method:: c_init_code_struct(node, struct_id)
+
+       Allows you to specify code that will be inserted in the struct
+       constructor of the Op.  This is for code which should be
+       executed once per thunk (Apply node, more or less).
+
+       `struct_id` is an integer guaranteed to be unique inside the
+       struct.
 
     .. method:: c_support_code()
 
@@ -77,30 +116,63 @@ There are less methods to define for an Op than for a Type:
 
     .. method:: c_support_code_apply(node, name)
 
-      Allows you to specify helper functions/structs specialized for a
-      particular apply of an :ref:`op`. Use `c_support_code` if the
-      code is the same for each apply of an op.
-      It will be inserted at global scope.
+       Allows you to specify helper functions/structs specialized for
+       a particular apply of an :ref:`op`. Use :meth:`c_support_code`
+       if the code is the same for each apply of an op.  It will be
+       inserted at global scope.
+
+    .. method:: c_support_code_struct(node, struct_id)
+
+       Allows you to specify helper functions of variables that will
+       be specific to one particular thunk.  These are inserted at
+       struct scope.
+
+       `struct_id` is an integer guaranteed to be unique inside the
+       struct.
+
+       :note:
+         You cannot specify kernels in the code returned by this since
+         that isn't supported by CUDA.  You should place your kernels
+         in :meth:`c_support_code()` or :meth:`c_support_code_apply()`
+         and call them from this code.
+
+    .. method:: c_cleanup_code_struct(node, struct_id)
+
+       Allows you to specify code that will be inserted in the struct
+       destructor of the Op.  This is for cleaninp up allocations and
+       stuff like this when the thunk is released (when you "free" a
+       compiled function using this op).
+
+       `struct_id` is an integer guaranteed to be unique inside the
+       struct.
 
     .. method:: infer_shape(node, (i0_shapes,i1_shapes,...))
 
-      Allow optimizations to lift the Shape op over this op.
-      An example of why this is good is when we only need the shape of a
-      variable: we will be able to obtain it without computing the variable
-      itself.
-      Must return a list where each element is a tuple representing the shape
-      of one output.
-      For example, for the matrix-matrix product ``infer_shape`` will have as
-      inputs (node, ((x0,x1), (y0,y1))) and should return [(x0, y1)]. Both the
-      inputs and the return value may be Theano variables.
+       Allow optimizations to lift the Shape op over this op.  An
+       example of why this is good is when we only need the shape of a
+       variable: we will be able to obtain it without computing the
+       variable itself.
+
+       Must return a list where each element is a tuple representing
+       the shape of one output.
+
+       For example, for the matrix-matrix product ``infer_shape`` will
+       have as inputs (node, ((x0,x1), (y0,y1))) and should return
+       [(x0, y1)]. Both the inputs and the return value may be Theano
+       variables.
 
     .. method:: c_code_cache_version()
 
-       Should return a tuple of hashable objects like integers. This
+       Must return a tuple of hashable objects like integers. This
        specifies the version of the code. It is used to cache the
        compiled code. You MUST change the returned tuple for each
-       change in the code. If you don't want to cache the compiled code
-       return an empty tuple or don't implement it.
+       change in the code. If you don't want to cache the compiled
+       code return an empty tuple or don't implement it.
+
+    .. method:: c_code_cache_version_apply(node)
+
+       Overrides :meth:`c_code_cache_version` if defined, but
+       otherwise has the same contract.
 
 The ``name`` argument is currently given an invalid value, so steer
 away from it. As was the case with Type, ``sub['fail']`` provides

theano/gof/cc.py

@@ -535,7 +535,6 @@ class CLinker(link.Linker):
         for variable in self.variables:
 
             # it might be possible to inline constant variables as C literals
-##            if getattr(variable, 'constant', False):
             # policy = [[what to declare in the struct,
             #            what to do at construction,
             #            what to do at destruction],
@@ -545,9 +544,6 @@ class CLinker(link.Linker):
             if variable in self.inputs:
                 # we need to extract the new inputs at each run
                 # they do not need to be relayed to Python, so we don't sync
-#                 if isinstance(variable, Constant):
-#                     raise TypeError("Inputs to CLinker cannot be Constant.",
-#                                     variable)
                 policy = [[get_nothing, get_nothing, get_nothing],
                           [get_c_declare, get_c_extract, get_c_cleanup]]
             elif variable in self.orphans:
@@ -619,15 +615,8 @@ class CLinker(link.Linker):
             id += 2
 
         for node_num, node in enumerate(self.node_order):
-
-            # We populate sub with a mapping from the variable names
-            # specified by the op's c_var_names method to the actual
-            # variable names that we will use.
-##            ivnames, ovnames = op.c_var_names()
+            # Why is this here?
             sub = dict(failure_var=failure_var)
-##            for variable, vname in zip(op.inputs + op.outputs,
-##                                       ivnames + ovnames):
-##                sub[vname] = symbol[variable]
 
             # The placeholder will be replaced by a hash of the entire
             # code (module + support code) in DynamicModule.code.
@@ -640,15 +629,15 @@ class CLinker(link.Linker):
             isyms = [symbol[r] for r in node.inputs]
             osyms = [symbol[r] for r in node.outputs]
 
-            # c_validate_update is deprecated
-            if hasattr(node.op, 'c_validate_update'):
-                raise Exception("c_validate_update is deprecated,"
-                                " move contents to c_code", node.op)
-
             # Make the CodeBlock for c_code
             sub['id'] = id
+            sub['struct_id'] = id + 1
             sub['fail'] = failure_code(sub)
 
+            struct_support = ""
+            struct_init = ""
+            struct_cleanup = ""
+
             op = node.op
             # type-specific support code
             try:
@@ -661,6 +650,7 @@ class CLinker(link.Linker):
                 assert isinstance(c_support_code_apply[-1], basestring), (
                     str(node.op) +
                     " didn't return a string for c_support_code_apply")
+
             try:
                 c_init_code_apply.append(op.c_init_code_apply(node, name))
             except utils.MethodNotDefined:
@@ -670,6 +660,30 @@ class CLinker(link.Linker):
                     str(node.op) +
                     " didn't return a string for c_init_code_apply")
 
+            try:
+                struct_init = op.c_init_code_struct(node, id + 1)
+                assert isinstance(struct_init, basestring), (
+                    str(node.op) +
+                    " didn't return a string for c_init_code_struct")
+            except utils.MethodNotDefined:
+                pass
+
+            try:
+                struct_support = op.c_support_code_struct(node, id + 1)
+                assert isinstance(struct_support, basestring), (
+                    str(node.op) +
+                    " didn't return a string for c_support_code_struct")
+            except utils.MethodNotDefined:
+                pass
+
+            try:
+                struct_cleanup = op.c_cleanup_code_struct(node, id + 1)
+                assert isinstance(struct_cleanup, basestring), (
+                    str(node.op) +
+                    " didn't return a string for c_cleanup_code_struct")
+            except utils.MethodNotDefined:
+                pass
+
             # emit c_code
             try:
                 behavior = op.c_code(node, name, isyms, osyms, sub)
@@ -694,6 +708,12 @@ class CLinker(link.Linker):
             tasks.append((node, 'code', id))
             id += 1
 
+            init_blocks.append(CodeBlock(struct_support, struct_init,
+                                         struct_cleanup, {'id': id}))
+            init_tasks.append((node, 'init', id))
+            id += 1
+
+
         # List of arg names for use in struct_gen. Note the call to
         # uniq: duplicate inputs must only be passed once because they
         # are mapped to the same name.  Duplicates are defined by (a
@@ -959,7 +979,8 @@ class CLinker(link.Linker):
             id += 2
         for node in self.node_order:
             tasks.append((node, 'code', id))
-            id += 1
+            init_tasks.append((node, 'init', id + 1))
+            id += 2
         return init_tasks, tasks
 
     def make_thunk(self, input_storage=None, output_storage=None,

theano/gof/cmodule.py

@@ -1522,8 +1522,6 @@ def gcc_llvm():
     It don't support all g++ parameters even if it support many of them.
     """
     if gcc_llvm.is_llvm is None:
-        pass
-        p = None
         try:
             p_out = output_subprocess_Popen(['g++', '--version'])
             output = p_out[0] + p_out[1]
@@ -1535,9 +1533,9 @@ def gcc_llvm():
             # compile when g++ is not available. If this happen, it
             # will crash later so supposing it is not llvm is "safe".
             output = b('')
-        del p
         gcc_llvm.is_llvm = b("llvm") in output
     return gcc_llvm.is_llvm
+
 gcc_llvm.is_llvm = None
 
 

theano/gof/op.py

@@ -126,22 +126,6 @@ class CLinkerObject(object):
         """
         return ()
 
-    def c_code_cache_version_apply(self, node):
-        """Return a tuple of integers indicating the version of this Op.
-
-        An empty tuple indicates an 'unversioned' Op that will not be cached between processes.
-
-        The cache mechanism may erase cached modules that have been superceded by newer
-        versions.  See `ModuleCache` for details.
-
-        :note: See also `c_code_cache_version()`
-
-        :note: This function overrides `c_code_cache_version` unless it explicitly calls
-        `c_code_cache_version`.  The default implementation simply calls `c_code_cache_version`
-        and ignores the `node` argument.
-        """
-        return self.c_code_cache_version()
-
     def c_compile_args(self):
         """Optional: Return a list of compile args recommended to compile the
         code returned by other methods in this class.
@@ -187,18 +171,6 @@ class CLinkerObject(object):
                                      self.__class__.__name__)
 
 
-    def c_init_code_apply(self, node, name):
-        """
-        Optional: return a list of code snippets specific to the apply
-        to be inserted in module initialization.
-
-        :Exceptions:
-         - `MethodNotDefined`: the subclass does not override this method
-        """
-        raise utils.MethodNotDefined("c_init_code_apply", type(self),
-                                     self.__class__.__name__)
-
-
 class CLinkerOp(CLinkerObject):
     """
     Interface definition for `Op` subclasses compiled by `CLinker`.
@@ -217,24 +189,26 @@ class CLinkerOp(CLinkerObject):
 
         :Parameters:
          `node` : Apply instance
-           WRITEME
-         `name` : WRITEME
-           WRITEME
+           The node for which we are compiling the current c_code.
+           The same Op may be used in more than one node.
+         `name` : A string
+           A name that is automatically assigned and guaranteed to be
+           unique.
          `inputs` : list of strings
-           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.
+           There is a string for each input of the function, and the
+           string is the name of a C variable pointing to that input.
+           The type of the variable depends on the declared type of
+           the input.  There is a corresponding python variable that
+           can be accessed by prepending "py_" to the name in the
+           list.
          `outputs` : list of strings
-           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.
+           Each string is the name of a C variable where the Op should
+           store its output.  The type depends on the declared type of
+           the output.  There is a corresponding python variable that
+           can be accessed by prepending "py_" to the name in the
+           list.  In some cases the outputs will be preallocated and
+           the value of the variable may be pre-filled.  The value for
+           an unallocated output is type-dependent.
          `sub` : dict of strings
            extra symbols defined in `CLinker` sub symbols (such as 'fail').
            WRITEME
@@ -246,52 +220,75 @@ class CLinkerOp(CLinkerObject):
         raise utils.MethodNotDefined('%s.c_code' \
                 % self.__class__.__name__)
 
-    def c_code_cleanup(self, node, name, inputs, outputs, sub):
-        """Optional: Return C code to run after c_code, whether it failed or not.
+    def c_code_cache_version_apply(self, node):
+        """Return a tuple of integers indicating the version of this Op.
 
-        QUESTION: is this function optional?
+        An empty tuple indicates an 'unversioned' Op that will not be
+        cached between processes.
+
+        The cache mechanism may erase cached modules that have been
+        superceded by newer versions.  See `ModuleCache` for details.
+
+        :note: See also `c_code_cache_version()`
+
+        :note: This function overrides `c_code_cache_version` unless
+               it explicitly calls `c_code_cache_version`.  The
+               default implementation simply calls
+               `c_code_cache_version` and ignores the `node` argument.
+        """
+        return self.c_code_cache_version()
+
+    def c_code_cleanup(self, node, name, inputs, outputs, sub):
+        """
+        Optional: Return C code to run after c_code, whether it failed
+                  or not.
 
         This is a convenient place to clean up things allocated by c_code().
 
         :Parameters:
          `node` : Apply instance
            WRITEME
-         `name` : WRITEME
-           WRITEME
+         `name` : A string
+           A name that is automatically assigned and guaranteed to be
+           unique.
          `inputs` : list of strings
-           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.
+           There is a string for each input of the function, and the
+           string is the name of a C variable pointing to that input.
+           The type of the variable depends on the declared type of
+           the input. There is a corresponding python variable that
+           can be accessed by prepending "py_" to the name in the
+           list.
          `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 C variable correspoinding to
+           one of the outputs of the Op. The type depends on the
+           declared type of the output. There is a corresponding
+           python variable that can be accessed by prepending "py_" to
+           the name in the list.
          `sub` : dict of strings
            extra symbols defined in `CLinker` sub symbols (such as 'fail').
            WRITEME
 
-        WRITEME
-
         :Exceptions:
          - `MethodNotDefined`: the subclass does not override this method
-
         """
         raise utils.MethodNotDefined('%s.c_code_cleanup' \
                 % self.__class__.__name__)
 
     def c_support_code_apply(self, node, name):
-        """Optional: Return utility code for use by an `Op` that will be inserted at global
-        scope, that can be specialized for the support of a particular `Apply` node.
+        """Optional: Return utility code for use by an `Op` that will be
+        inserted at global scope, that can be specialized for the
+        support of a particular `Apply` node.
 
         :param node: an Apply instance in the graph being compiled
 
-        :param node_id: a string or number that serves to uniquely identify this node.
-        Symbol names defined by this support code should include the node_id, so that they can
-        be called from the c_code, and so that they do not cause name collisions.
+        :param name: a string or number that serves to uniquely
+                     identify this node.  Symbol names defined by this
+                     support code should include the name, so that
+                     they can be called from the c_code, and so that
+                     they do not cause name collisions.
+
+        :note: This function is called in addition to c_support_code
+               and will supplement whatever is returned from there.
 
         :Exceptions:
          - `MethodNotDefined`: Subclass does not implement this method
@@ -300,6 +297,83 @@ class CLinkerOp(CLinkerObject):
         raise utils.MethodNotDefined("c_support_code_apply",
                 type(self), self.__class__.__name__)
 
+    def c_init_code_apply(self, node, name):
+        """
+        Optional: return a code string specific to the apply
+        to be inserted in the module initialization code.
+
+        :param node: an Apply instance in the graph being compiled
+
+        :param name: a string or number that serves to uniquely
+                     identify this node.  Symbol names defined by this
+                     support code should include the name, so that
+                     they can be called from the c_code, and so that
+                     they do not cause name collisions.
+
+        :note: This function is called in addition to c_init_code
+               and will supplement whatever is returned from there.
+
+        :Exceptions:
+         - `MethodNotDefined`: the subclass does not override this method
+        """
+        raise utils.MethodNotDefined("c_init_code_apply", type(self),
+                                     self.__class__.__name__)
+
+    def c_init_code_struct(self, node, struct_id):
+        """
+        Optional: return a code string specific to the apply
+        to be inserted in the struct initialization code.
+
+        :param node: an Apply instance in the graph being compiled
+
+        :param struct_id: a number that serves to uniquely identify
+                          this code.  The c_code will receive another
+                          sub parameter named struct_id that will
+                          contain this name.
+
+        :Exceptions:
+         - `MethodNotDefined`: the subclass does not override this method
+        """
+        raise utils.MethodNotDefined("c_init_code_apply", type(self),
+                                     self.__class__.__name__)
+
+    def c_support_code_struct(self, node, struct_id):
+        """Optional: Return utility code for use by an `Op` that will be
+        inserted at struct scope, that can be specialized for the
+        support of a particular `Apply` node.
+
+        :param node: an Apply instance in the graph being compiled
+
+        :param struct_id: a number that serves to uniquely identify
+                          this code.  The c_code will receive another
+                          sub parameter named struct_id that will
+                          contain this name.
+
+        :Exceptions:
+         - `MethodNotDefined`: Subclass does not implement this method
+
+        """
+        raise utils.MethodNotDefined("c_support_code_struct",
+                type(self), self.__class__.__name__)
+
+    def c_cleanup_code_struct(self, node, struct_id):
+        """
+        Optional: return a code string specific to the apply to be
+        inserted in the struct cleanup code.
+
+        :param node: an Apply instance in the graph being compiled
+
+        :param struct_id: a number that serves to uniquely identify
+                          this code.  The c_code will receive another
+                          sub parameter named struct_id that will
+                          contain this name.
+
+        :Exceptions:
+        - `MethodNotDefined`: the subclass does not override this method
+        """
+        raise utils.MethodNotDefined("c_cleanup_code_struct", type(self),
+                                     self.__class__.__name__)
+
 
 class PureOp(object):
     """
@@ -576,7 +650,7 @@ class Op(utils.object2, PureOp, CLinkerOp):
         self._op_use_c_code = use_c_code
 
     def _props(self):
-        return (getattr(self, a) for a in self.__props__)
+        return tuple(getattr(self, a) for a in self.__props__)
 
     def __hash__(self):
         if hasattr(self, '__props__'):

theano/gof/tests/test_op.py

@@ -75,6 +75,33 @@ class NoInputOp(Op):
         output_storage[0][0] = 'test Op no input'
 
 
+class StructOp(Op):
+    __props__ = ()
+
+    def do_constant_folding(self, node):
+        # we are not constant
+        return False
+
+    # The input only serves to distinguish thunks
+    def make_node(self, i):
+        return Apply(self, [i], [scalar.uint64()])
+
+    def c_support_code_struct(self, node, struct_id):
+        return "npy_uint64 counter%d;" % (struct_id,)
+
+    def c_init_code_struct(self, node, struct_id):
+        return "counter%d = 0;" % (struct_id,)
+
+    def c_code(self, node, name, input_names, outputs_names, sub):
+        return """
+%(out)s = counter%(sid)s;
+counter%(sid)s++;
+""" % dict(out=outputs_names[0], sid=sub['struct_id'])
+
+    def c_code_cache_version(self):
+        return (0,)
+
+
 class TestOp:
 
     # Sanity tests
@@ -102,6 +129,19 @@ class TestOp:
         rval = f()
         assert rval == 'test Op no input'
 
+    def test_op_struct(self):
+        sop = StructOp()
+        c = sop(theano.tensor.constant(0))
+        f = theano.function([], c)
+        rval = f()
+        assert rval == 0
+        rval = f()
+        assert rval == 1
+
+        c2 = sop(theano.tensor.constant(1))
+        f2 = theano.function([], [c, c2])
+        rval = f2()
+        assert rval == [0, 0]
 
 class TestMakeThunk(unittest.TestCase):
     def test_no_c_code(self):

theano/sandbox/gpuarray/basic_ops.py

@@ -63,6 +63,10 @@ class HideC(object):
     c_init_code = __hide
     c_init_code_apply = __hide
 
+    c_init_code_struct = __hide
+    c_support_code_struct = __hide
+    c_cleanup_code_struct = __hide
+
     def c_code_cache_version(self):
         return ()