Merge pull request #430 from LLNL/update-capptr

Add YAML group 'destructors'

Author: ltaylor16

docs/input.rst

@@ -294,49 +294,66 @@ a default argument may include a plus symbol:
 api
 ^^^
 
-Controls the API used by the C wrapper.  The values are *capi*,
-*buf*, *capsule*, *capptr*, *cdesc* and *cfi*.
-Normally, this attribute is determined by Shroud
-internally.  Scalar native types such as ``int`` and ``double`` will
-use *capi* since the argument can be passed directly to C using the
-*interoperability with C* feature of Fortran.
-
-Otherwise a 'bufferify' wrapper will also be created.  Pointers to native and
-``char`` use additional metadata extracted by the Fortran wrapper via
-intrinsics ``LEN`` and ``SIZE``.  In addition, *intent(in)* strings
-will be copied and null-terminated.  This uses *api(buf)*.
-
-*cdesc* will pass down a pointer to a struct which contains metadata
-for the argument instead of passing additional fields. The advantage
-is the struct can also be used to return metadata from the C wrapper
-to the Fortran wrapper.
-The metadata includes shape information from a *dimension* attribute
-and is used on *intent(OUT)* arguments and function results to set
-Fortran ``POINTER`` shapes.
-The struct is named by the format fields
-*C_array_type* and *F_array_type*.
-
-The option *F_CFI*, will use the *Further interoperability with C*
-features and pass ``CFI_cdesc_t`` arguments to the C where where the
-metadata is extracted.  This uses *api(cfi)*.
-
-The *capsule* and *capptr* APIs are used by the capsule created by
-shadow types created for C++ classes.  In both cases the result is
-passed from Fortran to C as an extra argument for function which
-return a class. With *capptr*, the C wrapper will return a pointer to
-the capsule argument while *capsule* will not return a value for
-the function. This is controlled by the *C_shadow_result* option.
-
-There is currently one useful case where the user would want to set
-this attribute. To avoid creating a wrapper which copies and null
-terminates a ``char *`` argument the user can set *api(capi)*.  The
-address of the formal parameter will be passed to the user's library.
-This is useful when null termination does not make sense. For example,
-when the argument is a large buffer to be written to a file.  The C
-library must have some other way of determining the length of the
-argument such as another argument with the explicit length.
+Controls the API used by the C wrapper.
+Normally, this attribute is determined by Shroud internally based on the
+argument type and attributes.
+But in some cases it's helpful if the user defines it.
+
+buf
+
+   Pass a pointer to a string along with meta data about the length
+   or size.
+   Pointers to native and
+   ``char`` use additional metadata extracted by the Fortran wrapper via
+   intrinsics ``LEN`` and ``SIZE``.  In addition, *intent(in)* strings
+   will be copied and null-terminated.
+
+capi
+
+    There is currently one useful case where the user would want to set
+    this attribute. To avoid creating a wrapper which copies and null
+    terminates a ``char *`` argument the user can set *api(capi)*.  The
+    address of the formal parameter will be passed to the user's library.
+    This is useful when null termination does not make sense. For example,
+    when the argument is a large buffer to be written to a file.  The C
+    library must have some other way of determining the length of the
+    argument such as another argument with the explicit length.
 
 .. tested by strings.yaml CpassCharPtrCAPI
+    
+capptr
+capsule
+
+    The *capsule* and *capptr* APIs are used by the capsule created by
+    shadow types created for C++ classes.  In both cases the result is
+    passed from Fortran to C as an extra argument for function which
+    return a class. With *capptr*, the C wrapper will return a pointer to
+    the capsule argument while *capsule* will not return a value for
+    the function. This is controlled by the **C_shadow_result** option.
+
+cdesc
+
+    Uses a struct to pass the metadata between Fortran and C.
+    This struct contains additional metadata beyond
+    the length and size used by *api(buf)*.
+    It is also used to return metadata from the C wrapper to the Fortran wrapper.
+    The metadata includes shape information from a *dimension* attribute
+    and is used on *intent(OUT)* arguments and function results to set the
+    shape of Fortran ``POINTER`` variables.
+    The struct is named by the format fields *C_array_type* and *F_array_type*.
+    It is similar to the ``CFI_cdesc_t`` struct provied by Fortran 2018.
+
+cfi
+
+    Use *Further interoperability with C* features and pass
+    ``CFI_cdesc_t`` arguments to the C wrapper which will extract the
+    metadata.  Using option *F_CFI* will make this the default
+    behavior.
+
+this
+
+    Used when the *return_this* field is *True*.
+    The C++ function returns a pointer to the **this** variable.
 
 .. In the future a user settable api might be useful to do custom
    actions in the wrappers.
@@ -510,6 +527,18 @@ scalar
 
 .. function pointers meta[deref] for both the +external and +funptr.
 
+destructor_name
+^^^^^^^^^^^^^^^
+
+Specifies a name in the **destructors** section which lists code to be used to 
+release memory.  Used with function results.
+It is used in the *C_memory_dtor_function* and will have the 
+variable ``void *ptr`` available as the pointer to the memory
+to be released.
+See :ref:`MemoryManagementAnchor` for details.
+
+..  and *intent(out)* arguments.
+
 dimension
 ^^^^^^^^^
 
@@ -589,18 +618,6 @@ as the dummy argument for the function pointer.
 See also the *funptr* attribute.
 See :ref:`DeclAnchor_Function_Pointers`.
 
-free_pattern
-^^^^^^^^^^^^
-
-A name in the **patterns** section which lists code to be used to 
-release memory.  Used with function results.
-It is used in the *C_memory_dtor_function* and will have the 
-variable ``void *ptr`` available as the pointer to the memory
-to be released.
-See :ref:`MemoryManagementAnchor` for details.
-
-..  and *intent(out)* arguments.
-
 funcarg
 ^^^^^^^
 

docs/pointers.rst

@@ -265,20 +265,24 @@ is used with ``std::vector`` and provides the lines:
     -  std::vector<{cxx_T}> *cxx_ptr = reinterpret_cast<std::vector<{cxx_T}> *>(ptr);
     -  delete cxx_ptr;
 
-Patterns can be used to provide code to free memory for a wrapped
-function.  The address of the memory to free will be in the variable
+Destructor code can be defined without creating a new statement group
+by defining it in the **destructors** section of the YAML file.  Then
+use the *+destructor_name* attribute in the declaration.
+This allows custom destructor code to be used more easily.
+
+The address of the memory to free will be in the variable
 ``void *ptr``, which should be referenced in the pattern:
 
 .. code-block:: yaml
 
     declarations:
-    - decl: char * getName() +free_pattern(free_getName)
+    - decl: char *getName() +destructor_name(free_getName)
 
-    patterns:
+    destructors:
        free_getName: |
           decref(ptr);
 
-Without any explicit *destructor_name* or pattern, ``free`` will be
+Without any explicit *destructor_name*, ``free`` will be
 used to release POD pointers; otherwise, ``delete`` will be used.
 
 .. When to use ``delete[] ptr``?
@@ -310,7 +314,8 @@ And :file:`wrapftutorial.f`:
 
 *addr* is the address of the C or C++ variable, such as a ``char *``
 or ``std::string *``.  *idtor* is a Shroud generated index of the
-destructor code defined by *destructor_name* or the *free_pattern* attribute.
+destructor code defined by *destructor_name* in the statement group
+or the *destructor_name* attribute.
 These code segments are collected and written to function
 *C_memory_dtor_function*.  A value of 0 indicated the memory will not
 be released and is used with the **owner(library)** attribute.

docs/releases.rst

@@ -18,6 +18,13 @@ Changes to YAML input
 * Added attribute *+funptr*. Uses ``type(C_FUNPTR)`` for
   function pointer arguments.
 
+* Renamed the *+free_pattern* attribute to *+destructor_name*.
+  The values is looked up in the new **destructors** section of
+  the YAML file instead of the **patterns** section.
+  Current use of *+free_pattern* is still supported but will
+  create a warning message in the logfile. The old usage will be
+  removed in a future version.
+  
 * Create an abstract interface for typedef statements which
   are function pointers. Previously, only function pointers
   arguments were supported.

regression/input/error.yaml

@@ -59,3 +59,16 @@ declarations:
     PY_array_arg: none
     PY_struct_arg: none
 
+
+#####
+# Report on old usage for free_pattern
+
+- decl: const std::string * getConstStringPtrOwnsAllocPattern() +owner(caller)
+  options:
+    wrap_python: False
+  fattrs:
+    free_pattern: C_string_free
+
+patterns:
+    C_string_free: |
+        // Used with +free_pattern(C_string_free)

regression/input/strings.yaml

@@ -142,7 +142,7 @@ declarations:
     description: |
       Similar to getConstStringPtrOwnsAlloc, but uses pattern to release memory.
   fattrs:
-    free_pattern: C_string_free
+    destructor_name: C_string_free
 
 - decl: const std::string * getConstStringPtrPointer()
             +deref(pointer)+owner(library)
@@ -310,9 +310,11 @@ patterns:
     C_invalid_name_buf: |
         // Some error code for buf
 
+destructors:
      # This pattern is added to C_memory_dtor_function
      # XXX - \t is not dealt with properly
     C_string_free: |
-        // Used with +free_pattern(C_string_free)
+        // Used with +destrucor_name(C_string_free)
         std::string *cxx_ptr = reinterpret_cast<std::string *>(ptr);
         delete cxx_ptr;
+

regression/reference/char-cxx-cfi/char.json

@@ -5466,6 +5466,11 @@
             }
         ],
         "language": "cxx",
+        "patterns": {
+            "C_invalid_name": "if ({cxx_var}.empty()) {{\n    return NULL;\n}}\n",
+            "C_invalid_name_buf": "// Some error code for buf\n",
+            "C_string_free": "// Used with +free_pattern(C_string_free)\nstd::string *cxx_ptr = reinterpret_cast<std::string *>(ptr);\ndelete cxx_ptr;\n"
+        },
         "scope_file": [
             "char"
         ],

regression/reference/char-cxx/char.json

@@ -6131,6 +6131,11 @@
             }
         ],
         "language": "cxx",
+        "patterns": {
+            "C_invalid_name": "if ({cxx_var}.empty()) {{\n    return NULL;\n}}\n",
+            "C_invalid_name_buf": "// Some error code for buf\n",
+            "C_string_free": "// Used with +free_pattern(C_string_free)\nstd::string *cxx_ptr = reinterpret_cast<std::string *>(ptr);\ndelete cxx_ptr;\n"
+        },
         "scope_file": [
             "char"
         ],

regression/reference/error-ast/output

@@ -108,13 +108,12 @@ Error in 'decl' field
    ^
 Expected EOF, found ID
 --------------------
-Node: testattrs4
-line 117
+Node: IndexType
 Typemap IndexType: Unknown key 'no_such_keyword'
 --------------------
-Node: testattrs4
-line 117
-Typemap IndexType: Replacing deprecated field 'f_c_module' with 'i_module'
+Node: IndexType
+typedef int64_t IndexType
+Deprecated: Typemap IndexType: Replacing deprecated field 'f_c_module' with 'i_module'
 --------------------
 Node: process_twostruct
 line 139