Merge pull request #2061 from abergeron/struct_support

doc/extending/cop.txt

@@ -31,76 +31,148 @@ 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.
+       *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.
+       Allows you to specify code that will be executed once when the
+       module is initialized, before anything else is executed.  This
+       is for code that will be executed once per Op.
+
+    .. method:: c_init_code_apply(node, name)
 
-    .. method:: c_init_code_apply(self, 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`.
 
-      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.
+    .. 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()
 
-      Allows you to specify helper functions/structs that the
-      :ref:`op` needs.  That code will be reused for each apply of
-      this op. It will be inserted at global scope.
+       Allows you to specify helper functions/structs that the
+       :ref:`op` needs.  That code will be reused for each apply of
+       this op. It will be inserted at global scope.
 
     .. 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/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 ()