stats.h File Reference

Structures and functions for statistics. More...

#include <freeradius-devel/util/pair.h>

Include dependency graph for stats.h:

Go to the source code of this file.

Data Structures
struct	fr_stats_instance_t
	Generic statistics structure. More...
struct	fr_stats_iter_t
	Iterator for a statistics structure. More...
struct	fr_stats_link_entry_t
	Link a struct entry to an autoloaded fr_dict_attr_t. More...
struct	fr_stats_link_t

Macros
#define	FR_STATS_ENTRY_DECL(_name, _var)   fr_stats_ ## _name ## _instance_t _var
	Macro used when declaring a variable which contains an instance of the statistics.
#define	FR_STATS_ENTRY_INIT(_name, _var, _mib)
	Macro used when initializing a variable which contains an instance of the statistics.
#define	FR_STATS_FIELD(_var, _field)   (_var)->stats.(_field)
	Macro used to reference a field in the statistics structure.
#define	FR_STATS_INC(_var, _field)   ((_var)->stats.(_field))++
	Macro used to increment one field in the statistics structure.
#define	FR_STATS_LINK_NAME(_name)   fr_stats_link_ ## _name ## _t
	Macro used when referencing a linking structure.
#define	FR_STATS_TYPEDEF(_name)
	Macro to define a typedef for a particular instance of statistics.
#define	STATS_HEADER_COMMON    fr_stats_link_t const *def
	Common header for all statistics instances.

Functions
int	fr_stats_from_pairs (TALLOC_CTX *ctx, fr_stats_instance_t *out, fr_pair_list_t const *list)
	Convert a statistics structure to fr_pair_t.
int	fr_stats_index_to_value_box (TALLOC_CTX *ctx, fr_value_box_t **out, fr_stats_instance_t const *in, unsigned int index)
	Convert the statistic at an index to a value-box.
void	fr_stats_iter_init (fr_stats_instance_t const *in, fr_stats_iter_t *iter)
	Initialize an iterator over a structure.
bool	fr_stats_iter_next (fr_stats_iter_t *iter)
	Go to the next entry in a structure.
int	fr_stats_iter_to_value_box (TALLOC_CTX *ctx, fr_value_box_t **out, fr_stats_iter_t *iter)
	Convert the statistic at the current iterator to a value-box.
int	fr_stats_merge_instance (fr_stats_instance_t *out, fr_stats_instance_t const *in)
	Public API for merging two statistics structures.
int	fr_stats_merge_value_box (fr_value_box_t *dst, fr_value_box_t const *src)
	Public API for merging two value-boxes based on their enums.
int	fr_stats_name_to_value_box (TALLOC_CTX *ctx, fr_value_box_t **out, fr_stats_instance_t const *inst, char const *name)
	Convert the statistic of a given name to a value-box.
int	fr_stats_to_pairs (TALLOC_CTX *ctx, fr_pair_list_t *out, fr_stats_instance_t const *in)
	Convert a statistics structure to fr_pair_t.

Detailed Description

Structures and functions for statistics.

Id

c1e479c383495da6bd4f59009d93c09298a87de0

Copyright

2022 Network RADIUS SAS (legal.nosp@m.@net.nosp@m.workr.nosp@m.adiu.nosp@m.s.com)

Definition in file stats.h.

---

Data Structure Documentation

fr_stats_instance_t

struct fr_stats_instance_t

Generic statistics structure.

Definition at line 65 of file stats.h.

Data Fields
uint8_t	stats[]	generic statistics data
	STATS_HEADER_COMMON	common header

fr_stats_iter_t

struct fr_stats_iter_t

Iterator for a statistics structure.

This is used internally, and there's no real need for code outside of the statistics library to use it.

Definition at line 75 of file stats.h.

Collaboration diagram for fr_stats_iter_t:

Data Fields
unsigned int	current
fr_stats_instance_t const *	inst

fr_stats_link_entry_t

struct fr_stats_link_entry_t

Link a struct entry to an autoloaded fr_dict_attr_t.

Definition at line 37 of file stats.h.

Collaboration diagram for fr_stats_link_entry_t:

Data Fields
fr_dict_attr_t const **	da_p	point to the autoload definition of the DA for this field
size_t	offset	from the start of the struct
size_t	size	size of this field
fr_type_t	type	cached for locality and simplicity

fr_stats_link_t

struct fr_stats_link_t

Definition at line 44 of file stats.h.

Collaboration diagram for fr_stats_link_t:

Data Fields
fr_stats_link_entry_t	entry[]	the field entries, in offset order
char const *	mib	MIB root.
char const *	name	name of the stats structure
size_t	num_elements	number of elements in the table. Note no "NULL" terminator
fr_dict_attr_t const **	root_p	point to the autoload definition of the DA for this structure
size_t	size	overall size of the structure

Macro Definition Documentation

FR_STATS_ENTRY_DECL

#define FR_STATS_ENTRY_DECL	(		_name,
			_var
	)		fr_stats_ ## _name ## _instance_t _var

Macro used when declaring a variable which contains an instance of the statistics.

Defines "fr_stats_name_instance_t var", which can be used in a structure

Code which needs to use some statistics can use this macro to declare a variable which contains stats for the local module / etc.

Definition at line 112 of file stats.h.

FR_STATS_ENTRY_INIT

#define FR_STATS_ENTRY_INIT	(		_name,
			_var,
			_mib
	)

Value:

        _var = (fr_stats_ ## _name ## _instance_t) {    \
                .def = fr_stats_link_ ## _name ## _t,   \
                .mib = _mib,                            \
                fr_stats_ ## _name ## _t stats = {},    \
               }

Macro used when initializing a variable which contains an instance of the statistics.

var = .... initializer for the stats instance ...

Code which needs to use some statistics can use this macro to initialize a variable which contains stats for the local module / etc.

Definition at line 121 of file stats.h.

FR_STATS_FIELD

#define FR_STATS_FIELD	(		_var,
			_field
	)		(_var)->stats.(_field)

Macro used to reference a field in the statistics structure.

Code which needs to mangle a field of the statistics can use this macro to get the correct field name.

Definition at line 140 of file stats.h.

FR_STATS_INC

#define FR_STATS_INC	(		_var,
			_field
	)		((_var)->stats.(_field))++

Macro used to increment one field in the statistics structure.

Code which needs to update some statistics can use this macro to increment a variable which contains stats for the local module / etc.

Definition at line 134 of file stats.h.

FR_STATS_LINK_NAME

#define FR_STATS_LINK_NAME

(

_name

)

fr_stats_link_ ## _name ## _t

Macro used when referencing a linking structure.

.def = FR_STATS_LINK_NAME(radius_auth_serv),

This is used internally, and there's no real need for code outside of the statistics library to use it.

Definition at line 103 of file stats.h.

FR_STATS_TYPEDEF

#define FR_STATS_TYPEDEF

(

_name

)

Value:

        typedef struct {                \
                STATS_HEADER_COMMON;    \
                fr_stats_ ## _name ## _t        stats;   \
        } fr_stats_ ## _name ## _instance_t

Macro to define a typedef for a particular instance of statistics.

Defines fr_stats_name_instance_t which contains an instance of the statistics for fr_stats_name_t, and which points to the linking structure fr_stats_link_name_t.

Note that nothing needs to refer to the base statistics structure: fr_stats_name_t. All of that is wrapped in an instance definition.

This is used internally, and there's no real need for code outside of the statistics library to use it.

Definition at line 91 of file stats.h.

STATS_HEADER_COMMON

#define STATS_HEADER_COMMON    fr_stats_link_t const *def

Common header for all statistics instances.

def pointer to the linking definition of the structure for this instance

Todo:

• if we need additional tracking data (rb trees, dlists, etc.), they can go here.

Definition at line 59 of file stats.h.

Function Documentation

fr_stats_from_pairs()

int fr_stats_from_pairs	(	TALLOC_CTX *	ctx,
		fr_stats_instance_t *	inst,
		fr_pair_list_t const *	list
	)

Convert a statistics structure to fr_pair_t.

Parameters

[in]	ctx	talloc ctx
[out]	inst	where the output pairs will be stored
[in]	list	pairs where we read the pairs from

Definition at line 114 of file stats.c.

Here is the call graph for this function:

fr_stats_index_to_value_box()

int fr_stats_index_to_value_box	(	TALLOC_CTX *	ctx,
		fr_value_box_t **	out,
		fr_stats_instance_t const *	inst,
		unsigned int	index
	)

Convert the statistic at an index to a value-box.

Parameters

[in]	ctx	the talloc context
[out]	out	the value-box to return
[in]	inst	data structure defining this instance of the statistics
[in]	index	the field index of the structure to use

Returns

• 0 for success, and *out is non-NULL
• <0 for error (memory allocation failed, index is invalid, etc), and *out is NULL

Definition at line 343 of file stats.c.

Here is the call graph for this function:

Here is the caller graph for this function:

fr_stats_iter_init()

void fr_stats_iter_init	(	fr_stats_instance_t const *	inst,
		fr_stats_iter_t *	iter
	)

Initialize an iterator over a structure.

Parameters

[in]	inst	data structure defining this instance of the statistics
[out]	iter	the initialized iterator

Definition at line 309 of file stats.c.

fr_stats_iter_next()

bool fr_stats_iter_next

(

fr_stats_iter_t *

iter

)

Go to the next entry in a structure.

Parameters

[in]

iter

the iterator

Returns

• true for continue the iteration
• false for the iteration is done

Definition at line 322 of file stats.c.

fr_stats_iter_to_value_box()

int fr_stats_iter_to_value_box	(	TALLOC_CTX *	ctx,
		fr_value_box_t **	out,
		fr_stats_iter_t *	iter
	)

Convert the statistic at the current iterator to a value-box.

Parameters

[in]	ctx	the talloc context
[out]	out	the value-box to return
[in]	iter	the iterator, which points to the current entry.

Returns

• 0 for success, and *out is non-NULL
• <0 for error (memory allocation failed, index is invalid, etc), and *out is NULL

Definition at line 416 of file stats.c.

Here is the call graph for this function:

fr_stats_merge_instance()

int fr_stats_merge_instance	(	fr_stats_instance_t *	out,
		fr_stats_instance_t const *	in
	)

Public API for merging two statistics structures.

Parameters

[out]	out	where the merged stats are written to
[in]	in	source stats to merge into out

Returns

• 0 on success
• <0 on the two instances are not compatible.

Definition at line 241 of file stats.c.

Here is the call graph for this function:

fr_stats_merge_value_box()

int fr_stats_merge_value_box	(	fr_value_box_t *	dst,
		fr_value_box_t const *	src
	)

Public API for merging two value-boxes based on their enums.

Parameters

[in,out]	dst	where the merged stats are written to
[in]	src	source stats to merge into dst

Returns

• 0 on success
• <0 on the two boxes are not compatible, or we cannot merge the given data type

Definition at line 260 of file stats.c.

fr_stats_name_to_value_box()

int fr_stats_name_to_value_box	(	TALLOC_CTX *	ctx,
		fr_value_box_t **	out,
		fr_stats_instance_t const *	inst,
		char const *	name
	)

Convert the statistic of a given name to a value-box.

Parameters

[in]	ctx	the talloc context
[out]	out	the value-box to return
[in]	inst	data structure defining this instance of the statistics
[in]	name	the field name in the structure

Returns

• 0 for success, and *out is non-NULL
• <0 for error (memory allocation failed, name is invalid, etc), and *out is NULL

Definition at line 435 of file stats.c.

Here is the call graph for this function:

fr_stats_to_pairs()

int fr_stats_to_pairs	(	TALLOC_CTX *	ctx,
		fr_pair_list_t *	out,
		fr_stats_instance_t const *	inst
	)

Convert a statistics structure to fr_pair_t.

Parameters

[in]	ctx	talloc ctx
[out]	out	where the output pairs will be stored
[in]	inst	data structure defining this instance of the statistics

Definition at line 33 of file stats.c.

Here is the call graph for this function: