atexit.h File Reference

Functions to help with cleanup. More...

#include <stdatomic.h>
#include <pthread.h>
#include <freeradius-devel/util/talloc.h>

Include dependency graph for atexit.h:

Go to the source code of this file.

Macros
#define	__Thread_local
#define	fr_atexit_global(_func, _uctx)   _atexit_global(__FILE__, __LINE__, _func, _uctx)
	Add a free function to the global free list.
#define	fr_atexit_global_once(_init, _free, _uctx)
#define	fr_atexit_thread_local(_name, _free, _uctx)
#define	fr_atexit_thread_local_disarm(...)   fr_atexit_global_disarm(__VA_ARGS__)
#define	fr_atexit_thread_local_disarm_all(...)   fr_atexit_global_disarm_all(__VA_ARGS__)
#define	fr_atexit_thread_trigger_all(...)

Typedefs
typedef int(*	fr_atexit_t) (void *uctx)
	Destructor callback.

Functions
int	_atexit_global (char const *file, int line, fr_atexit_t func, void const *uctx)
	Add a free function to be called when the process exits.
unsigned int	fr_atexit_global_disarm (bool uctx_scope, fr_atexit_t func, void const *uctx)
	Remove a specific global destructor (without executing it)
void	fr_atexit_global_disarm_all (void)
	Remove all global destructors (without executing them)
int	fr_atexit_global_setup (void)
	Setup the atexit handler, should be called at the start of a program's execution.
int	fr_atexit_global_trigger_all (void)
	Cause all global free triggers to fire.
bool	fr_atexit_is_exiting (void)
	Return whether we're currently in the teardown phase.
bool	fr_atexit_thread_local_alloc_disabled (void)
	Has fr_atexit_thread_local_disable_alloc been called yet.
void	fr_atexit_thread_local_disable_alloc (void)
	Disable lazy allocation of thread-local caches for the rest of the process.
int	fr_atexit_trigger (bool uctx_scope, fr_atexit_t func, void const *uctx)
	Iterates through all thread local destructor lists, causing destructor to be triggered.

Detailed Description

Functions to help with cleanup.

Simplifies cleaning up thread local and global resources

Copyright

2020-2022 Arran Cudbard-Bell (a.cud.nosp@m.bard.nosp@m.b@fre.nosp@m.erad.nosp@m.ius.o.nosp@m.rg)

2013-2016 The FreeRADIUS server project

Definition in file atexit.h.

Macro Definition Documentation

__Thread_local

#define __Thread_local

Definition at line 213 of file atexit.h.

fr_atexit_global

#define fr_atexit_global	(		_func,
			_uctx
	)		_atexit_global(__FILE__, __LINE__, _func, _uctx)

Add a free function to the global free list.

Parameters

[in]	_func	to call.
[in]	_uctx	to pass to func.

Returns

• 0 on success.
• -1 on failure.

Definition at line 58 of file atexit.h.

fr_atexit_global_once

#define fr_atexit_global_once	(		_init,
			_free,
			_uctx
	)

Value:

do { \
        static bool _init_done = false; \
        void * _our_uctx = _uctx; /* stop _uctx being evaluated multiple times, it may be a call to malloc() */ \
        if (unlikely(!_init_done)) { \
                _init(_our_uctx); \
                fr_atexit_global(_free, _our_uctx); \
                _init_done = true; \
        } \
} while(0);

Definition at line 214 of file atexit.h.

fr_atexit_thread_local

#define fr_atexit_thread_local	(		_name,
			_free,
			_uctx
	)

Value:

do { \
        static bool _init_done = false; \
        void * _our_uctx = _uctx; /* stop _uctx being evaluated multiple times, it may be a call to malloc() */ \
        if (unlikely(!_init_done)) { \
                fr_atexit_global(_free, _our_uctx); \
                _init_done = true; \
        } \
        _name = _our_uctx; \
} while(0);

Definition at line 224 of file atexit.h.

fr_atexit_thread_local_disarm

#define fr_atexit_thread_local_disarm

(

...

)

fr_atexit_global_disarm(__VA_ARGS__)

Definition at line 234 of file atexit.h.

fr_atexit_thread_local_disarm_all

#define fr_atexit_thread_local_disarm_all

(

...

)

fr_atexit_global_disarm_all(__VA_ARGS__)

Definition at line 235 of file atexit.h.

fr_atexit_thread_trigger_all

#define fr_atexit_thread_trigger_all

(

...

)

Definition at line 236 of file atexit.h.

Typedef Documentation

fr_atexit_t

typedef int(* fr_atexit_t) (void *uctx)

Destructor callback.

Parameters

[in]

uctx

to free.

Returns

• 0 on success.
• -1 on failure.

Definition at line 44 of file atexit.h.

Function Documentation

_atexit_global()

int _atexit_global	(	char const *	file,
		int	line,
		fr_atexit_t	func,
		void const *	uctx
	)

Add a free function to be called when the process exits.

Definition at line 229 of file atexit.c.

Here is the call graph for this function:

fr_atexit_global_disarm()

unsigned int fr_atexit_global_disarm	(	bool	uctx_scope,
		fr_atexit_t	func,
		void const *	uctx
	)

Remove a specific global destructor (without executing it)

Note

This function's primary purpose is to help diagnose issues with destructors from within a debugger.

Parameters

[in]	uctx_scope	Only process entries where the func and scope both match.
[in]	func	Entries matching this function will be disarmed.
[in]	uctx	associated with the entry.

Returns

How many global destructors were disarmed.

Definition at line 248 of file atexit.c.

Here is the call graph for this function:

Here is the caller graph for this function:

fr_atexit_global_disarm_all()

void fr_atexit_global_disarm_all

(

void

)

Remove all global destructors (without executing them)

Note

This function's primary purpose is to help diagnose issues with destructors from within a debugger.

Definition at line 278 of file atexit.c.

Here is the call graph for this function:

Here is the caller graph for this function:

fr_atexit_global_setup()

int fr_atexit_global_setup

(

void

)

Setup the atexit handler, should be called at the start of a program's execution.

Definition at line 179 of file atexit.c.

Here is the call graph for this function:

Here is the caller graph for this function:

fr_atexit_global_trigger_all()

int fr_atexit_global_trigger_all

(

void

)

Cause all global free triggers to fire.

This is necessary when libraries (perl) register their own atexit handlers using the normal POSIX mechanism, and we need to ensure all our atexit handlers fire before so any global deinit is done explicitly by us.

Returns

• >= 0 The number of atexit handlers triggered on success.
• <0 the return code from any atexit handlers that returned an error.

Definition at line 305 of file atexit.c.

Here is the call graph for this function:

Here is the caller graph for this function:

fr_atexit_is_exiting()

bool fr_atexit_is_exiting

(

void

)

Return whether we're currently in the teardown phase.

When this function returns true no more thread local or global destructors can be added.

Definition at line 452 of file atexit.c.

Here is the caller graph for this function:

fr_atexit_thread_local_alloc_disabled()

bool fr_atexit_thread_local_alloc_disabled

(

void

)

Has fr_atexit_thread_local_disable_alloc been called yet.

Definition at line 442 of file atexit.c.

Here is the caller graph for this function:

fr_atexit_thread_local_disable_alloc()

void fr_atexit_thread_local_disable_alloc

(

void

)

Disable lazy allocation of thread-local caches for the rest of the process.

Call this from main before fr_atexit_thread_trigger_all(). After it returns, every TLS-pool initialiser that consults fr_atexit_thread_local_alloc_disabled() falls back to the un-cached path, so _Thread_local slots in other threads aren't read after the trigger frees their backing memory.

Definition at line 434 of file atexit.c.

fr_atexit_trigger()

int fr_atexit_trigger	(	bool	uctx_scope,
		fr_atexit_t	func,
		void const *	uctx
	)

Iterates through all thread local destructor lists, causing destructor to be triggered.

This should only be called by the main process not by threads.

The main purpose of the function is to force cleanups at a specific time for problematic destructors.

Parameters

[in]	uctx_scope	Only process entries where the func and scope both match.
[in]	func	Entries matching this function will be triggered.
[in]	uctx	associated with the entry.

Returns

• >= 0 The number of atexit handlers triggered on success.
• <0 the return code from any atexit handlers that returned an error.

Definition at line 350 of file atexit.c.

Here is the call graph for this function:

Here is the caller graph for this function: