title: Scope-Based Resource Management

Scope-Based Resource Management (SBRM)

Apache Celix provides auto pointers and auto values as a lightweight form of scope-based resource management in C. These features are inspired by the RAII (Resource Acquisition Is Initialization) paradigm from C++, as well as ideas from Scope-based resource management for the kernel.

Using the macros defined in celix_cleanup.h and related headers (celix_stdio_cleanup.h, celix_stdlib_cleanup.h), resources are automatically released when their associated variables go out of scope. This enables safer and more concise C code, especially when handling early returns or error paths.

Defining Cleanup Functions

Before using auto cleanup, types must opt-in by defining a cleanup function.

  • For pointer types:
  CELIX_DEFINE_AUTOPTR_CLEANUP_FUNC(celix_filter_t, celix_filter_destroy)
  • For value types:
CELIX_DEFINE_AUTO_CLEANUP_CLEAR_FUNC(celix_mutex_lock_guard_t, celixMutexLockGuard_deinit)

Using Auto Pointers and Auto Values

Auto Pointers

Use celix_autoptr(type) to declare a pointer that will be cleaned up automatically:

void my_function(void) {
    celix_autoptr(celix_filter_t) filter = celix_filter_create("(foo=bar)");
    // use filter
} // filter is destroyed automatically

To transfer ownership and disable automatic cleanup, use:

celix_filter_t* raw = celix_steal_ptr(filter);

Auto Values

Use celix_auto(type) to declare a value-based resource with automatic cleanup:

void my_function(void) {
    celix_auto(celix_mutex_lock_guard_t) lock = celixMutexLockGuard_init(&myMutex);
    // use guarded memory
} // lock guard is cleaned up automatically (myMutex is unlocked)

Benefits

Celix's SBRM features allow for:

  • Simplified cleanup logic
  • RAII-style early returns
  • Cleaner, more maintainable C code