Merge remote-tracking branch 'upstream/feature/574-scope-based-resour…

…ce-management' into feature/574-scope-based-resource-management

documents/README.md

@@ -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. 
@@ -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)

documents/c_patterns.md

@@ -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.