Writing C interface code

Introduction

Since t8code is primarily a C++ library a proper C interface is necessary. The current status is a mix of C and C++ code.

For the future, when t8code will have been settled on a matured C++ API, the goal is to provide a C interface via automatic code generation.

Till then, we write C interfaces/wrappers by hand.

Coding Guideline

C interface code is written side by side with t8code's C++ sources. The C interface/wrapper functions are simply added at the bottom of the C++ source files. The following mockup gives an example how this looks like.

// file: t8code/src/t8_module/t8_some_functionality.cxx

int SomeClass::member_function {...args...} {

};

// At the bottom of the CXX source file we find the related
// C interface function wrapped in `T8_EXTERN_C_{BEGIN,END} ();` blocks.

T8_EXTERN_C_BEGIN ();

int t8_SomeClass_member_function(SomeClass_t *obj, ...arguments...) {
  return obj->member_function(...args...); 
}

T8_EXTERN_C_END ();

Alongside the C++ file an accompanying C header file makes the interface/wrapper available to any C application.

// file: t8code/src/t8_module/t8_some_class.h

/**
 * Doxygen documentation.
 */
int
t8_SomeClass_member_function(SomeClass_t *obj, ...arguments...);