Cleanup Helper Interface

Macros
#define	SCOPE_VAR_DEFINE(_name, _type, _exit_fn, _init_fn, ...)
	Define a scoped variable type.
#define	SCOPE_GUARD_DEFINE(_name, _type, _lock, _unlock)
	Define a scoped guard type.
#define	SCOPE_DEFER_DEFINE(_func, ...)
	Define a scoped defer type.
#define	scope_var(_name, _var)
	Declare a variable with automatic cleanup.
#define	scope_var_init(_name, _var, _init_expr)
	Declare a variable with automatic cleanup using direct initialization.
#define	scope_guard(_name)
	Acquire a scoped guard lock.
#define	scope_defer(_name)
	Register a scoped deferred call.

Detailed Description

Macro Definition Documentation

scope_defer

#define scope_defer

(

_name

)

#include <zephyr/cleanup.h>

Value:

scope_var(defer_##_name, Z_UNIQUE_ID(defer))

Register a scoped deferred call.

This macro creates a defer variable with an automatically generated unique name. The defer will execute its cleanup action when going out of scope.

Parameters

_name

Name of the defer type (defined by SCOPE_DEFER_DEFINE or SCOPE_VAR_DEFINE with defer_ prefix)

Attention

Available only when the following Kconfig option is enabled: CONFIG_SCOPE_CLEANUP_HELPERS.

Usage:

scope_defer(k_mutex_unlock)(&my_mutex); 

SCOPE_DEFER_DEFINE

#define SCOPE_DEFER_DEFINE	(		_func,
			... )

#include <zephyr/cleanup.h>

Value:

        COND_CODE_0(NUM_VA_ARGS(__VA_ARGS__),                                                      \
                    (Z_SCOPE_DEFER_DEFINE_VOID(_func)),                                            \
                    (Z_SCOPE_DEFER_DEFINE_N(_func, __VA_ARGS__)))

Define a scoped defer type.

This macro defines a defer that executes a cleanup function when the variable goes out of scope. Unlike guards, defers don't acquire a resource on initialization.

Parameters

_func	The function to call at cleanup
...	The argument types to pass to the cleanup function

Attention

Available only when the following Kconfig option is enabled: CONFIG_SCOPE_CLEANUP_HELPERS.

Usage:

SCOPE_DEFER_DEFINE(k_free, void *);

scope_guard

#define scope_guard

(

_name

)

#include <zephyr/cleanup.h>

Value:

scope_var(guard_##_name, Z_UNIQUE_ID(guard))

Acquire a scoped guard lock.

This macro creates a guard variable with an automatically generated unique name. The guard will acquire the lock on initialization and release it when going out of scope.

Parameters

_name

Name of the guard type (defined by SCOPE_GUARD_DEFINE or SCOPE_VAR_DEFINE with guard_ prefix)

Attention

Available only when the following Kconfig option is enabled: CONFIG_SCOPE_CLEANUP_HELPERS.

Usage:

scope_guard(k_mutex)(&my_mutex); 

SCOPE_GUARD_DEFINE

#define SCOPE_GUARD_DEFINE	(		_name,
			_type,
			_lock,
			_unlock )

#include <zephyr/cleanup.h>

Value:

        SCOPE_VAR_DEFINE(                                                                          \
                guard_##_name, _type, if (_T != NULL) { _unlock; }, ({                             \
                        _lock;                                                                     \
                        _T;                                                                        \
                }),                                                                                \
                _type _T)

Define a scoped guard type.

This macro defines a guard that automatically acquires a lock on initialization and releases it when going out of scope.

Parameters

_name	Name of the guard (will be prefixed with guard_)
_type	Type of the lock object (typically a pointer)
_lock	Expression to acquire the lock (can reference _T)
_unlock	Expression to release the lock (can reference _T)

Attention

Available only when the following Kconfig option is enabled: CONFIG_SCOPE_CLEANUP_HELPERS.

Usage:

SCOPE_GUARD_DEFINE(k_mutex, struct k_mutex *,
                   (void)k_mutex_lock(_T, K_FOREVER),
                   (void)k_mutex_unlock(_T));

scope_var

#define scope_var	(		_name,
			_var )

#include <zephyr/cleanup.h>

Value:

        cleanup_##_name##_t _var __cleanup(cleanup_##_name##_exit) = cleanup_##_name##_init

Declare a variable with automatic cleanup.

This macro declares a variable with automatic cleanup using a previously defined cleanup helper. The variable will be automatically cleaned up when it goes out of scope.

The variable is initialized by calling the init function defined in SCOPE_VAR_DEFINE. Use scope_var_init if you want to initialize the variable with a direct expression instead of calling the init function.

Parameters

_name	Name of the cleanup helper (defined by SCOPE_VAR_DEFINE)
_var	Name of the variable to declare

Attention

Available only when the following Kconfig option is enabled: CONFIG_SCOPE_CLEANUP_HELPERS.

Usage:

scope_var(some_type, my_var)(init_args); 

See also

scope_var_init for direct initialization without calling the init function

SCOPE_VAR_DEFINE

#define SCOPE_VAR_DEFINE	(		_name,
			_type,
			_exit_fn,
			_init_fn,
			... )

#include <zephyr/cleanup.h>

Value:

        static inline void __maybe_unused cleanup_##_name##_exit(_type *p)                         \
        {                                                                                          \
                _type _T = *p;                                                                     \
                _exit_fn;                                                                          \
        }                                                                                          \
        static inline _type __maybe_unused cleanup_##_name##_init(__VA_ARGS__)                     \
        {                                                                                          \
                _type t = _init_fn;                                                                \
                return t;                                                                          \
        }                                                                                          \
        typedef _type cleanup_##_name##_t

Define a scoped variable type.

This macro defines a new cleanup helper that can be used with the __cleanup attribute to automatically execute cleanup code when a variable goes out of scope.

Parameters

_name	Name of the cleanup helper
_type	Type of the variable to be cleaned up
_exit_fn	Cleanup code to execute when variable goes out of scope (can reference _T)
_init_fn	Initialization expression for the variable
...	Initialization arguments (variadic)

The macro creates:

• An exit function cleanup_<name>_exit that executes cleanup code
• An init function cleanup_<name>_init that initializes the variable
• A typedef cleanup_<name>_t for the type

Attention

Available only when the following Kconfig option is enabled: CONFIG_SCOPE_CLEANUP_HELPERS.

Usage:

struct foo {
    int value;
};
 
static inline struct foo *foo_constructor(int value)
{
    struct foo *ptr = k_malloc(sizeof(struct foo));
 
    if (ptr != NULL) {
        ptr->value = value;
    }
 
    return ptr;
}
 
static inline void foo_destructor(struct foo *ptr)
{
    k_free(ptr);
}
 
// Define the cleanup helper
SCOPE_VAR_DEFINE(foo, struct foo *, foo_destructor(_T), foo_constructor(val), int val);
 
static int some_function(void)
{
    // The scope_var macro declares 'f' with automatic cleanup
    scope_var(foo, f)(42);
    if (f == NULL) {
        return -ENOMEM;
    }
 
    // Use f normally - it points to an allocated and initialized struct foo
    printk("Value: %d\n", f->value);
 
    // No need to manually free - foo_destructor is called automatically
    // when 'f' goes out of scope
}

scope_var_init

#define scope_var_init	(		_name,
			_var,
			_init_expr )

#include <zephyr/cleanup.h>

Value:

        cleanup_##_name##_t _var __cleanup(cleanup_##_name##_exit) = (_init_expr)

Declare a variable with automatic cleanup using direct initialization.

This macro declares a variable with automatic cleanup using a previously defined cleanup helper. The variable will be automatically cleaned up when it goes out of scope.

Unlike scope_var, this macro accepts a direct initialization expression instead of calling the init function defined in SCOPE_VAR_DEFINE. Use this when you need to bypass the init function and initialize the variable directly (e.g., with a struct initializer, a different function, or a literal value).

Parameters

_name	Name of the cleanup helper (defined by SCOPE_VAR_DEFINE)
_var	Name of the variable to declare
_init_expr	Direct initialization expression for the variable (e.g., {0}, NULL, or a function call)

Attention

Available only when the following Kconfig option is enabled: CONFIG_SCOPE_CLEANUP_HELPERS.

Usage:

scope_var_init(some_type, my_var, {0}); 

See also

scope_var for initialization using the init function