#include <freeradius-devel/server/base.h>
#include <freeradius-devel/server/dl_module.h>
#include <freeradius-devel/server/map.h>
#include <freeradius-devel/protocol/freeradius/freeradius.internal.h>

Include dependency graph for rlm_cache.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	rlm_cache_config_t
	Configuration for the rlm_cache module. More...

struct	rlm_cache_driver_s

struct	rlm_cache_entry_t

struct	rlm_cache_t

Macros
#define	MAX_ATTRMAP 128

Typedefs
typedef int(*	cache_acquire_t) (void *handle, rlm_cache_config_t const config, void instance, request_t request)
	Acquire a handle to access the cache. More...

typedef rlm_cache_entry_t (	cache_entry_alloc_t) (rlm_cache_config_t const config, void instance, request_t *request)
	Allocate a new cache entry. More...

typedef uint64_t(*	cache_entry_count_t) (rlm_cache_config_t const config, void instance, request_t request, void handle)
	Get the number of entries in the cache. More...

typedef cache_status_t(*	cache_entry_expire_t) (rlm_cache_config_t const config, void instance, request_t request, void handle, fr_value_box_t const *key)
	Remove an entry from the cache. More...

typedef cache_status_t(*	cache_entry_find_t) (rlm_cache_entry_t *out, rlm_cache_config_t const config, void instance, request_t request, void handle, fr_value_box_t const key)
	Retrieve an entry from the cache. More...

typedef void(*	cache_entry_free_t) (rlm_cache_entry_t *c)
	Free a cache entry. More...

typedef cache_status_t(*	cache_entry_insert_t) (rlm_cache_config_t const config, void instance, request_t request, void handle, rlm_cache_entry_t const *c)
	Insert an entry into the cache. More...

typedef cache_status_t(*	cache_entry_set_ttl_t) (rlm_cache_config_t const config, void instance, request_t request, void handle, rlm_cache_entry_t *c)
	Update the ttl of an entry in the cache. More...

typedef int(*	cache_reconnect_t) (rlm_cache_handle_t *handle, rlm_cache_config_t const config, void instance, request_t request)
	Reconnect a previously acquired handle. More...

typedef void(*	cache_release_t) (rlm_cache_config_t const config, void instance, request_t request, rlm_cache_handle_t handle)
	Release a previously acquired handle. More...

typedef struct rlm_cache_driver_s	rlm_cache_driver_t

typedef void	rlm_cache_handle_t

Enumerations
enum	cache_status_t { CACHE_RECONNECT = -2 , CACHE_ERROR = -1 , CACHE_OK = 0 , CACHE_MISS = 1 }

Data Structure Documentation

◆ rlm_cache_config_t

struct rlm_cache_config_t

Configuration for the rlm_cache module.

This is separate from the rlm_cache_t struct, to limit driver's visibility of rlm_cache instance data.

Definition at line 51 of file rlm_cache.h.

Collaboration diagram for rlm_cache_config_t:

Data Fields
int32_t	epoch	Time after which entries are considered valid.
uint32_t	max_entries	Maximum entries allowed.
bool	stats	Generate statistics.
fr_time_delta_t	ttl	How long an entry is valid for.

◆ rlm_cache_driver_s

struct rlm_cache_driver_s

Definition at line 257 of file rlm_cache.h.

Collaboration diagram for rlm_cache_driver_s:

Data Fields
cache_acquire_t	acquire	(optional) Acquire exclusive access to a resource used to retrieve the cache entry.
cache_entry_alloc_t	alloc	(optional) Allocate a new entry.
module_t	common	Common fields for all loadable modules.
cache_entry_count_t	count	(Optional) Number of entries currently in the cache.
cache_entry_expire_t	expire	Remove an old entry.
cache_entry_find_t	find	Retrieve an existing cache entry.
cache_entry_free_t	free	(optional) Free memory used by an entry.
cache_entry_insert_t	insert	Add a new entry.
call_env_parse_pair_t	key_parse	(optional) custom key parser. Allows the driver to have complete control over how the key is parsed. If not provided, the default key parser will be used. data will be set to the submodule's instance data, NOT the rlm_cache_t.
cache_reconnect_t	reconnect	(optional) Re-initialise resource.
cache_release_t	release	(optional) Release access to resource acquired with acquire callback.
cache_entry_set_ttl_t	set_ttl	(Optional) Update the TTL of an entry.

◆ rlm_cache_entry_t

struct rlm_cache_entry_t

Definition at line 72 of file rlm_cache.h.

Collaboration diagram for rlm_cache_entry_t:

Data Fields
fr_unix_time_t	created	When the entry was created.
fr_unix_time_t	expires	When the entry expires.
long long int	hits	How many times the entry has been retrieved.
fr_value_box_t	key	Key used to identify entry.
map_list_t	maps	Head of the maps list.

◆ rlm_cache_t

struct rlm_cache_t

Definition at line 65 of file rlm_cache.h.

Collaboration diagram for rlm_cache_t:

Data Fields
rlm_cache_config_t	config	Must come first because of icky hacks.
rlm_cache_driver_t const *	driver	Driver's exported interface.
module_instance_t *	driver_submodule	Driver's instance data.

Macro Definition Documentation

◆ MAX_ATTRMAP

#define MAX_ATTRMAP 128

Definition at line 37 of file rlm_cache.h.

Typedef Documentation

◆ cache_acquire_t

typedef int(* cache_acquire_t) (void **handle, rlm_cache_config_t const *config, void *instance, request_t *request)

Acquire a handle to access the cache.

Note: This callback is optional. If it's not provided the handle argument to other callbacks will be NULL.

Parameters

[out]	handle	Where to write pointer to handle to access the cache with.
[in]	config	for this instance of the rlm_cache module.
[in]	instance	Driver specific instance data.
[in]	request	The current request.

Returns

0 on success.
-1 on failure.

Definition at line 226 of file rlm_cache.h.

◆ cache_entry_alloc_t

typedef rlm_cache_entry_t*(* cache_entry_alloc_t) (rlm_cache_config_t const *config, void *instance, request_t *request)

Allocate a new cache entry.

Definition at line 84 of file rlm_cache.h.

◆ cache_entry_count_t

typedef uint64_t(* cache_entry_count_t) (rlm_cache_config_t const *config, void *instance, request_t *request, void *handle)

Get the number of entries in the cache.

Note: This callback is optional. Though max_entries will not be enforced if it is not provided.

Parameters

[in]	config	for this instance of the rlm_cache module.
[in]	instance	Driver specific instance data.
[in]	request	The current request.
	handle	the driver gave us when we called cache_acquire_t, or NULL if no cache_acquire_t callback was provided.

Returns: number of entries in the cache.

Definition at line 210 of file rlm_cache.h.

◆ cache_entry_expire_t

typedef cache_status_t(* cache_entry_expire_t) (rlm_cache_config_t const *config, void *instance, request_t *request, void *handle, fr_value_box_t const *key)

Remove an entry from the cache.

Note: This callback is not optional.

Parameters

[in]	config	for this instance of the rlm_cache module.
[in]	instance	Driver specific instance data.
[in]	request	The current request.
[in]	handle	the driver gave us when we called cache_acquire_t, or NULL if no cache_acquire_t callback was provided.
[in]	key	of entry to expire.

Returns

CACHE_RECONNECT - If handle needs to be reinitialised/reconnected.
CACHE_ERROR - If the entry couldn't be expired.
CACHE_OK - If the entry was expired.
CACHE_MISS - If the entry didn't exist, so couldn't be expired.

Definition at line 172 of file rlm_cache.h.

◆ cache_entry_find_t

typedef cache_status_t(* cache_entry_find_t) (rlm_cache_entry_t **out, rlm_cache_config_t const *config, void *instance, request_t *request, void *handle, fr_value_box_t const *key)

Retrieve an entry from the cache.

If a cache entry is found, but the cache entry needs to be deserialized, the driver is expected to allocate an appropriately sized rlm_cache_entry_t, perform the deserialisation, and write a pointer to the new entry to out, returning CACHE_OK.

If the rlm_cache_handle_t is inviable, the driver should return CACHE_RECONNECT, to have it reinitialised/reconnected.

Parameters

[out]	out	Where to write a pointer to the retrieved entry (if there was one).
[in]	config	for this instance of the rlm_cache module.
[in]	instance	Driver specific instance data.
[in]	request	The current request.
[in]	handle	the driver gave us when we called cache_acquire_t, or NULL if no cache_acquire_t callback was provided.
[in]	key	to use to lookup cache entry

Returns

CACHE_RECONNECT - If handle needs to be reinitialised/reconnected.
CACHE_ERROR - If the lookup couldn't be completed.
CACHE_OK - Lookup was successful.
CACHE_MISS - No cached entry was found.

Definition at line 121 of file rlm_cache.h.

◆ cache_entry_free_t

typedef void(* cache_entry_free_t) (rlm_cache_entry_t *c)

Free a cache entry.

Note: This callback is optional, but the driver assume responsibility for freeing the cache_entry_t on cache_entry_expire_t.

If the driver does not need to keep a local copy of the cache entry, it should provide a callback to free the memory previously allocated for the cache entry by cache_entry_find_t or by rlm_cache.

Parameters

c	entry to free.

Definition at line 97 of file rlm_cache.h.

◆ cache_entry_insert_t

typedef cache_status_t(* cache_entry_insert_t) (rlm_cache_config_t const *config, void *instance, request_t *request, void *handle, rlm_cache_entry_t const *c)

Insert an entry into the cache.

Serialize (if necessary) the entry passed to us, and write it to the cache with the key c->key.

The cache entry should not be freed by the driver, irrespective of success or failure. If the entry needs to be freed after insertion because a local copy should not be kept, the driver should provide a cache_entry_free_t callback.

If the rlm_cache_handle_t is inviable, the driver should return CACHE_RECONNECT, to have it reinitialised/reconnected.

Note: This callback is not optional.; This callback must overwrite existing cache entries on insert.

Parameters

config	for this instance of the rlm_cache module.
instance	Driver specific instance data.
request	The current request.
handle	the driver gave us when we called cache_acquire_t, or NULL if no cache_acquire_t callback was provided.
c	to insert.

Returns

CACHE_RECONNECT - If handle needs to be reinitialised/reconnected.
CACHE_ERROR - If the insert couldn't be completed.
CACHE_OK - If the insert was successful.

Definition at line 152 of file rlm_cache.h.

◆ cache_entry_set_ttl_t

typedef cache_status_t(* cache_entry_set_ttl_t) (rlm_cache_config_t const *config, void *instance, request_t *request, void *handle, rlm_cache_entry_t *c)

Update the ttl of an entry in the cache.

Note: This callback optional. If it's not specified the cache code will expire and recreate the entry with a new TTL.

If the rlm_cache_handle_t is inviable, the driver should return CACHE_RECONNECT, to have it reinitialised/reconnected.

Parameters

[in]	config	for this instance of the rlm_cache module.
[in]	instance	Driver specific instance data.
[in]	request	The current request.
[in]	handle	the driver gave us when we called cache_acquire_t, or NULL if no cache_acquire_t callback was provided.
[in]	c	to update the TTL of. c->ttl will have been set to the new value.

Returns

CACHE_RECONNECT - If handle needs to be reinitialised/reconnected.
CACHE_ERROR - If the entry TTL couldn't be updated.
CACHE_OK - If the entry's TTL was updated.

Definition at line 195 of file rlm_cache.h.

◆ cache_reconnect_t

typedef int(* cache_reconnect_t) (rlm_cache_handle_t **handle, rlm_cache_config_t const *config, void *instance, request_t *request)

Reconnect a previously acquired handle.

Note: This callback is optional.

Parameters

[in,out]	handle	to reinitialise/reconnect.
[in]	config	for this instance of the rlm_cache module.
[in]	instance	Driver specific instance data.
[in]	request	The current request.

Returns

0 on success.
-1 on failure.

Definition at line 254 of file rlm_cache.h.

◆ cache_release_t

typedef void(* cache_release_t) (rlm_cache_config_t const *config, void *instance, request_t *request, rlm_cache_handle_t *handle)

Release a previously acquired handle.

Note: This callback is optional.

Parameters

[in]	config	for this instance of the rlm_cache module.
[in]	instance	Driver specific instance data.
[in]	request	The current request.
[in]	handle	to release.

Definition at line 238 of file rlm_cache.h.

◆ rlm_cache_driver_t

typedef struct rlm_cache_driver_s rlm_cache_driver_t

Definition at line 1 of file rlm_cache.h.

◆ rlm_cache_handle_t

typedef void rlm_cache_handle_t

Definition at line 35 of file rlm_cache.h.

Enumeration Type Documentation

◆ cache_status_t

enum cache_status_t

Enumerator
CACHE_RECONNECT	Handle needs to be reconnected.
CACHE_ERROR	Fatal error.
CACHE_OK	Cache entry found/updated.
CACHE_MISS	Cache entry notfound.

Definition at line 39 of file rlm_cache.h.

Data Structures

Macros

Typedefs

Enumerations

Data Structure Documentation

◆ rlm_cache_config_t

◆ rlm_cache_driver_s

◆ rlm_cache_entry_t

◆ rlm_cache_t

Macro Definition Documentation

◆ MAX_ATTRMAP

Typedef Documentation

◆ cache_acquire_t

◆ cache_entry_alloc_t

◆ cache_entry_count_t

◆ cache_entry_expire_t

◆ cache_entry_find_t

◆ cache_entry_free_t

◆ cache_entry_insert_t

◆ cache_entry_set_ttl_t

◆ cache_reconnect_t

◆ cache_release_t

◆ rlm_cache_driver_t

◆ rlm_cache_handle_t

Enumeration Type Documentation

◆ cache_status_t