Skip to content

Commit

Permalink
Add initial (user) documentation for SBRM
Browse files Browse the repository at this point in the history
  • Loading branch information
pnoltes committed Jul 27, 2023
1 parent 49aca53 commit d16d359
Show file tree
Hide file tree
Showing 2 changed files with 93 additions and 0 deletions.
5 changes: 5 additions & 0 deletions documents/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,9 @@ These `services` can be used directly or in a declarative way using `components`
To run a selection of bundles, an Apache Celix `container` executable can be created. An Apache Celix `containter` will
start an Apache Celix framework and install and start the provided bundles.

## C Patterns
Apache Celix is written in C and uses some C patterns to improve the development experience.

## Bundles
An Apache Celix Bundle is a zip file which contains a collection of shared libraries,
configuration files and optional an activation entry.
Expand Down Expand Up @@ -79,6 +82,8 @@ bundles contains binaries depending on the stdlibc++ library.
* Building
* [Building and Installing Apache Celix](building/README.md)
* [Building and Developing Apache Celix with CLion](building/dev_celix_with_clion.md)
* C Patterns
* [Apache Celix C Patterns](c_patterns.md)
* Framework
* [Apache Celix Bundles](bundles.md)
* [Apache Celix Services](services.md)
Expand Down
88 changes: 88 additions & 0 deletions documents/c_patterns.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
---
title: Introduction
---

<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->

# Apache Celix C Patterns

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.

## Apache Celix C Objects

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 create and a destroy function. The create function is used to create
a new object, and the destroy function is used to destroy the object. The destroy function should also 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 C Container Types

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 C Scope-Based Resource Management

Apache Celix offers several macros to support scope-based resource management (SBRM). These macros are
inspired by [Scoped-based Resource Management for the Kernel](https://lwn.net/Articles/934838/).

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 "define" macro, which determines the
expected C functions to clean up the object.

## Support for Resource Allocation Is Initialization (RAII)-like Structures

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. 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:
- `celixThreadMutexLocker_new`
- `celix_service_reg_t`

Special effort is made to ensure that these constructs do not require additional allocation and should provide minimal
to no additional overhead.

## Polymorphism in Apache Celix

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.

0 comments on commit d16d359

Please sign in to comment.