C Statements¶

Note

Work in progress

extern "C" {

{C_return_type} {C_name}({C_prototype})
{
    {c_pre_call}
    {c_call_code}   {call}    arg_call
    {post_call_pattern}
    {c_post_call}
    {c_final}
    {c_return}
}

C_prototype -> c_arg_decl

A corresponding bind(C) interface can be created for Fortran.

{F_C_subprogram} {F_C_name}({F_C_arguments}) &
    {F_C_result_clause} &
    bind(C, name="{C_name}")
    f_c_module / f_c_module_line
    f_c_import
    f_c_arg_decl
    f_c_result_decl
end {F_C_subprogram} {F_C_name}

Where F_C_clause = F_C_arguments = f_c_arg_names F_C_result_clause = f_c_result_var

Lookup statements¶

The statements for an argument are looked up by converting the type and attributes into an underscore delimited string.

language - c
intent - in, out, inout, function, ctor, dtor, getter, setter
group from typemap. native
pointer - scalar, *, **
api - from attribute buf, capsule, capptr, cdesc and cfi.
deref - from attribute allocatable, pointer, raw, result-as-arg, scalar

template¶

Each template argument is appended to the initial statement name. targ, group and pointer

c_statements¶

name¶

A name can contain variants separated by /.

- name: c_in/out/inout_native_*_cfi

This is equivelent to having three groups:

- name: c_in_native_*_cfi
- name: c_out_native_*_cfi
- name: c_inout_native_*_cfi

iface_header¶

List of header files which will be included in the generated header for the C wrapper. These headers must be C only and will be included after ifdef __cplusplus. Used for headers needed for declarations in c_arg_decl. Can contain headers required for the generated prototypes.

For example, ISO_Fortran_binding.h is C only.

impl_header¶

A list of header files which will be added to the C wrapper implementation. These headers may include C++ code.

c_helper¶

A blank delimited list of helper functions which will be added to the wrapper file. The list will be formatted to allow for additional flexibility:

c_helper: capsule_data_helper vector_context vector_copy_{cxx_T}

These functions are defined in whelper.py. There is no current way to add additional functions.

cxx_local_var¶

If a local C++ variable is created for an argument by pre_call, cxx_local_var indicates if the local variable is a pointer, scalar or result. .. This sets cxx_var is set to SH_{c_var}. This will properly dereference the variable when passed to the C++ function. It will also set the format fields cxx_member. For example, a std::string argument is created for the C++ function from the char * argument passed into the C API wrapper.

       name="c_inout_string",
       cxx_local_var="scalar",
       pre_call=["{c_const}std::string {cxx_var}({c_var});"],

Set to **return** when the *c_var* is passed in as an argument and
a C++ variable must be created.
Ex ``c_function_shadow``.
In this case, *cxx_to_c* is defined so a local variable will already
be created, unless *language=c* in which case *cxx_to_c* is unneeded.

c_arg_decl¶

A list of declarations to append to the prototype in the C wrapper. Defaults to None which will cause Shroud to generate an argument from the wrapped function’s argument. An empty list will cause no declaration to be added. Functions do not add arguments by default. A trailing semicolon will be provided.

Note

c_arg_decl, i_arg_decl, and i_arg_names must all exist in a group and have the same number of names.

i_arg_decl¶

A list of dummy argument declarations in the Fortran bind(C) interface. The variable to be declared is c_var. i_module can be used to add USE statements needed by the declarations. An empty list will cause no declaration to be added.

Note

c_arg_decl, i_arg_decl, and i_arg_names must all exist in a group and have the same number of names.

i_arg_names¶

Names of arguments to pass to C function. Defaults to {F_C_var}. An empty list will cause no declaration to be added.

Note

c_arg_decl, i_arg_decl, and i_arg_names must all exist in a group and have the same number of names.

i_result_decl¶

A list of declarations in the Fortran interface for a function result value.

i_import¶

List of names to import into the Fortran interface. The names will be expanded before being used.

In this example, Shroud creates F_array_type derived type in the module and it is used in the interface.

i_import=["{F_array_type}"],

i_module¶

Fortran modules used in the Fortran interface:

i_module=dict(iso_c_binding=["C_PTR"]),

i_module_line¶

Fortran modules used in the Fortran interface as a single line which allows format strings to be used.

i_module_line="iso_c_binding:{f_kind}",

The format is:

module ":" symbol [ "," symbol ]* [ ";" module ":" symbol [ "," symbol ]* ]

c_arg_call¶

c_pre_call¶

Code used with intent(in) arguments to convert from C to C++.

c_call¶

Code to call function. This is usually generated. An exception which require explicit call code are constructors and destructors for shadow types.

c_post_call¶

Code used with intent(out) arguments and function results. Can be used to convert results from C++ to C.

c_final¶

Inserted after post_call and before ret. Can be used to release intermediate memory in the C wrapper.

c_return¶

List of code for return statement. Usually generated but can be replaced. For example, with constructors.

Useful to convert a subroutine into a function. For example, convert a void function which fills a std::vector to return the number of items.

c_return_type¶

Explicit return type when it is different than the functions return type. For example, with shadow types.

c_return_type: long
c_return:
- return Darg->size;

return_type can also be used to convert a C wrapper into a void function. This is useful for functions which return pointers but the pointer value is assigned to a subroutine argument which holds the pointer (For example, CFI_cdesc_t). The type(C_PTR) which would be return by the C wrapper is unneeded by the Fortran wrapper.

destructor_name¶

A name for the destructor code in destructor. Must be unique. May include format strings:

destructor_name: std_vector_{cxx_T}

destructor¶

A list of lines of code used to delete memory. Usually allocated by a pre_call statement. The code is inserted into C_memory_dtor_function which will provide the address of the memory to destroy in the variable void *ptr. For example:

destructor:
-  std::vector<{cxx_T}> *cxx_ptr = reinterpret_cast<std::vector<{cxx_T}> *>(ptr);
-  delete cxx_ptr;

owner¶

Set owner of the memory. Similar to attribute owner.

Used where the new` operator is part of the generated code. For example where a class is returned by value or a constructor. The C wrapper must explicitly allocate a class instance which will hold the value from the C++ library function. The Fortran shadow class must keep this copy until the shadow class is deleted.

Defaults to library.

c_temps¶

A list of suffixes for temporary variable names.

   c_temps=["len"]

Create variable names in the format dictionary using
``{fmt.c_temp}{rootname}_{name}``.
For example, argument *foo* creates *SHT_foo_len*.

c_local¶

Similar to temps but uses {fmt.C_local}{rootname}_{name}. temps is intended for arguments and is typically used in a mixin group. local is used by group to generate names for local variables. This allows creating names without conflicting with temps from a mixin group.

lang_c and lang_cxx¶

Language specific versions of each field can be added to these dictionaries. The version which corresponds to the YAML file language field will be used.

lang_c=dict(
    impl_header=["<stddef.h>"],
),
lang_cxx=dict(
    impl_header=["<cstddef>"],
),