C Statements¶
Note
Work in progress
extern "C" {
{C_return_type} {C_name}({C_prototype}) buf_args
{
{pre_call}
{call_code} arg_call
{post_call_pattern}
{post_call}
{final}
{ret}
}
c_statements¶
buf_args¶
buf_args lists the arguments which are used by the C wrapper. The default is to provide a one-for-one correspondance with the arguments of the function which is being wrapped. However, often an additional function is created which will pass additional or different arguments to provide meta-data about the argument.
The Fortran wrapper will call the generated ‘bufferified’ function and provide the meta-data to the C wrapper.
arg
Use the library argument as the wrapper argument. This is the default when buf_args is not explicit.
- arg_decl
- The explicit declarations will be provided in the fields c_arg_decl and f_arg_decl.
capsule
An argument of type C_capsule_data_type/F_capsule_data_type. It provides a pointer to the C++ memory as well as information to release the memory.
context
An argument of C_array_type/F_array_type. For example, used with
std::vector
to hold address and size of data contained in the argument in a form which may be used directly by Fortran.c_var_context options.C_var_context_template
len
Result of Fortran intrinsicLEN
for string arguments. Typeint
.
len_trim
Result of Fortran intrinsicLEN_TRIM
for string arguments. Typeint
.
size
Result of Fortran intrinsicSIZE
for array arguments. Typelong
.
shadow
Argument will be of type C_capsule_data_type.
arg
default.
shadow size capsule context len_trim len
buf_extra¶
Used to add argument for return values. For example, function which return class instance.
c_header¶
List of blank delimited header files which will be included by the generated header
for the C wrapper. These headers must be C only.
For example, size_t
requires stddef.h:
type: size_t
fields:
c_type: size_t
cxx_type: size_t
c_header: <stddef.h>
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.
c_local_var¶
If a local C variable is created for the return value by post_call, c_local_var indicates if the local variable is a pointer or scalar. For example, when a structure is returned by a C++ function, the C wrapper creates a local variable which contains a pointer to the C type of the struct.
The local variable can be passed in when buf_args is shadow.
If true, generate a local variable using the C declaration for the argument.
This variable can be used by the pre_call and post_call statements.
A single declaration will be added even if with intent(inout)
.
cxx_header¶
A blank delimited list of header files which will be added to the C wrapper implementation. These headers may include C++ code.
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 or scalar.
.. This sets cxx_var is set to SH_{c_var}
.
This in turns will 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.
c_arg_decl¶
A list of declarations in the C wrapper when buf_arg includes “arg_decl”.
f_arg_decl¶
A list of declarations in the Fortran interface when buf_arg includes “arg_decl”.
The variable to be declared is c_var.
f_module can be used to add USE
statements.
f_result_decl¶
A list of declarations in the Fortran interface for a function result value.
arg_call¶
pre_call¶
Code used with intent(in) arguments to convert from C to C++.
call¶
Code to call function. This is usually generated. An exception which require explicit call code are constructors and destructors for shadow types.
post_call¶
Code used with intent(out) arguments and function results. Can be used to convert results from C++ to C.
final¶
Inserted after post_call and before ret. Can be used to release intermediate memory in the C wrapper.
ret¶
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.
return_type¶
Explicit return type when it is different than the functions return type. For example, with shadow types.
return_type: long
ret:
- return Darg->size;
return_cptr¶
If true, the function will return a C pointer. This will be
used by the Fortran interface to declare the function as
type(C_PTR)
.
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.