The core of Apache Celix is written in C, as C can serve as a common denominator for many languages. However, C lacks the concept of classes and objects, scope-based resource management - for concepts like RAII -, and other modern C++ features. To somewhat overcome this, Apache Celix employs several patterns.
It’s important to note that ideally, all Apache Celix C code follows the patterns described in this section, but this isn’t always the case. Particularly, older code may not always adhere to these patterns.
The first pattern is the Apache Celix C object pattern. This pattern is used to create, destroy, and manage objects in a C manner. A C object is implemented using an opaque pointer to a struct, which contains object details invisible to the object’s user. The C object should provide C functions to create, destroy, and manipulate the object.
The naming scheme used for the object struct is <celix_object_name>, typically with a typedef to
<celix_object_name>_t. For the object functions, the following naming scheme is
used: <celix_objectName>_<functionName>. Note the camelCase for the object name and function name.
An Apache Celix C object should always have a constructor and a destructor. If memory allocation is involved,
a celix_<objectName>_create function is used to create and return a new object, and a celix_<objectName>_destroy
function is used to destroy the object and free the object’s memory. Otherwise, use a celix_<objectName>_init function
with celix_status_t return value to initialize the object’s provided memory and use a celix_<objectName>_deinit
function to deinitialize the object. The celix_<objectName>_deinit function should not free the object’s memory.
An Apache Celix C object can also have additional functions to access object information or to manipulate the object. If an object contains properties, it should provide a getter and setter function for each property.
Apache Celix provides several container types: celix_array_list, celix_properties, celix_string_hash_map,
and celix_long_hash_map. Although these containers are not type-safe, they offer additional functions to handle
different element types. Refer to the header files for more information.
Apache Celix offers several macros to add support for scope-based resource management (SBRM) to existing types. These macros are inspired by Scoped-based Resource Management for the Kernel.
The main macros used for SBRM are:
celix_autofree: Automatically frees memory with free when the variable goes out of scope.celix_auto: Automatically calls a value-based cleanup function when the variable goes out of scope.celix_autoptr: Automatically calls a pointer-based cleanup function when the variable goes out of scope.celix_steal_ptr: Used to “steal” a pointer from a variable to prevent automatic cleanup when the variable goes
out of scope.These macros can be found in the Apache Celix utils headers celix_cleanup.h and celix_stdlib_cleanup.h.
In Apache Celix, C objects must opt into SBRM. This is done by using a CELIX_DEFINE_AUTO macro, which determines the
expected C functions to clean up the object.
Based on the previously mentioned SBRM, Apache Celix also offers support for structures that resemble RAII.
These can be used to guard locks, manage service registration, etc. These guards should follow the naming convention
celix_<obj_to_guard>_guard_t. Support for RAII-like structures is facilitated by providing
additional cleanup functions that work with either the celix_auto or celix_autoptr macros.
Examples include:
celix_mutex_lock_guard_tcelix_service_registration_guard_tSpecial effort is made to ensure that these constructs do not require additional allocation and should provide minimal to no additional overhead.
It’s worth mentioning that the above-mentioned patterns and additions do not add support for polymorphism. Although this could be a welcome addition, Apache Celix primarily handles polymorphism through the use of services, both for itself and its users. Refer to the “Apache Celix Services” section for more information.