rlm_cache_htrie.c File Reference

Simple htrie based cache. More...

#include <freeradius-devel/server/base.h>
#include <freeradius-devel/util/heap.h>
#include <freeradius-devel/util/debug.h>
#include <freeradius-devel/util/value.h>
#include <freeradius-devel/util/htrie.h>
#include "../../rlm_cache.h"
#include "lib/server/cf_parse.h"
#include "lib/server/tmpl.h"
#include "lib/util/types.h"

Include dependency graph for rlm_cache_htrie.c:

Go to the source code of this file.

Data Structures
struct	rlm_cache_htrie_entry_t
struct	rlm_cache_htrie_t

Functions
static int	cache_acquire (void **handle, UNUSED rlm_cache_config_t const *config, void *instance, request_t *request)
	Lock the htrie. More...
static rlm_cache_entry_t *	cache_entry_alloc (UNUSED rlm_cache_config_t const *config, UNUSED void *instance, request_t *request)
	Custom allocation function for the driver. More...
static uint64_t	cache_entry_count (UNUSED rlm_cache_config_t const *config, void *instance, request_t *request, UNUSED void *handle)
	Return the number of entries in the cache. More...
static cache_status_t	cache_entry_expire (UNUSED rlm_cache_config_t const *config, void *instance, request_t *request, UNUSED void *handle, fr_value_box_t const *key)
	Free an entry and remove it from the data store. More...
static cache_status_t	cache_entry_find (rlm_cache_entry_t **out, UNUSED rlm_cache_config_t const *config, void *instance, request_t *request, UNUSED void *handle, fr_value_box_t const *key)
	Locate a cache entry. More...
static cache_status_t	cache_entry_insert (rlm_cache_config_t const *config, void *instance, request_t *request, void *handle, rlm_cache_entry_t const *c)
	Insert a new entry into the data store. More...
static cache_status_t	cache_entry_set_ttl (UNUSED rlm_cache_config_t const *config, void *instance, request_t *request, UNUSED void *handle, rlm_cache_entry_t *c)
	Update the TTL of an entry. More...
static int8_t	cache_heap_cmp (void const *one, void const *two)
	Compare two entries by expiry time. More...
static void	cache_release (UNUSED rlm_cache_config_t const *config, void *instance, request_t *request, UNUSED rlm_cache_handle_t *handle)
	Release an entry unlocking any mutexes. More...
static int	cf_htrie_key_parse (TALLOC_CTX *ctx, void *out, tmpl_rules_t const *t_rules, CONF_ITEM *ci, void const *data, UNUSED call_env_parser_t const *rule)
	Custom key parsing function for checking compatibility of key types. More...
static int	cf_htrie_type_parse (TALLOC_CTX *ctx, void *out, void *parent, CONF_ITEM *ci, conf_parser_t const *rule)
	Custom htrie type parsing function. More...
static int	mod_detach (module_detach_ctx_t const *mctx)
	Cleanup a cache_htrie instance. More...
static int	mod_instantiate (module_inst_ctx_t const *mctx)
	Create a new cache_htrie instance. More...

Variables
static conf_parser_t	driver_config []
rlm_cache_driver_t	rlm_cache_htrie

Detailed Description

Simple htrie based cache.

Id

e45787a9e5f311b7822aaf40e2381572394aa7c8

Copyright

2024 Arran Cudbard-Bell a.cud.nosp@m.bard.nosp@m.b@fre.nosp@m.erad.nosp@m.ius.o.nosp@m.rg

2014 The FreeRADIUS server project

Definition in file rlm_cache_htrie.c.

---

Data Structure Documentation

rlm_cache_htrie_entry_t

struct rlm_cache_htrie_entry_t

Definition at line 53 of file rlm_cache_htrie.c.

Collaboration diagram for rlm_cache_htrie_entry_t:

Data Fields
rlm_cache_entry_t	fields	Entry data.
fr_heap_index_t	heap_id	Offset used for expiry heap.

rlm_cache_htrie_t

struct rlm_cache_htrie_t

Definition at line 39 of file rlm_cache_htrie.c.

Collaboration diagram for rlm_cache_htrie_t:

Data Fields
fr_htrie_t *	cache	Tree for looking up cache keys.
fr_heap_t *	heap	For managing entry expiry.
bool	htrie_auto	Whether the user wanted to automatically configure the htrie.
fr_htrie_type_t	htype	The htrie type we'll be using.
fr_type_t	ktype	When htrie is "auto", we use this type to decide what type of tree to use.
pthread_mutex_t	mutex	Protect the tree from multiple readers/writers.

Function Documentation

cache_acquire()

static int cache_acquire ( void **  handle, UNUSED rlm_cache_config_t const *  config, void *  instance, request_t *  request  )

static

Lock the htrie.

Note

handle not used except for sanity checks.

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 354 of file rlm_cache_htrie.c.

cache_entry_alloc()

static rlm_cache_entry_t* cache_entry_alloc ( UNUSED rlm_cache_config_t const *  config, UNUSED void *  instance, request_t *  request  )

static

Custom allocation function for the driver.

Allows allocation of cache entry structures with additional fields.

Definition at line 177 of file rlm_cache_htrie.c.

cache_entry_count()

static uint64_t cache_entry_count ( UNUSED rlm_cache_config_t const *  config, void *  instance, request_t *  request, UNUSED void *  handle  )

static

Return the number of entries in the cache.

Note

handle not used except for sanity checks.

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 338 of file rlm_cache_htrie.c.

Here is the call graph for this function:

cache_entry_expire()

static cache_status_t cache_entry_expire ( UNUSED rlm_cache_config_t const *  config, void *  instance, request_t *  request, UNUSED void *  handle, fr_value_box_t const *  key  )

static

Free an entry and remove it from the data store.

Note

handle not used except for sanity checks.

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 239 of file rlm_cache_htrie.c.

Here is the call graph for this function:

Here is the caller graph for this function:

cache_entry_find()

static cache_status_t cache_entry_find ( rlm_cache_entry_t **  out, UNUSED rlm_cache_config_t const *  config, void *  instance, request_t *  request, UNUSED void *  handle, fr_value_box_t const *  key  )

static

Locate a cache entry.

Note

handle not used except for sanity checks.

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 197 of file rlm_cache_htrie.c.

Here is the call graph for this function:

cache_entry_insert()

static cache_status_t cache_entry_insert ( rlm_cache_config_t const *  config, void *  instance, request_t *  request, void *  handle, rlm_cache_entry_t const *  c  )

static

Insert a new entry into the data store.

Note

handle not used except for sanity checks.

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 267 of file rlm_cache_htrie.c.

Here is the call graph for this function:

cache_entry_set_ttl()

static cache_status_t cache_entry_set_ttl ( UNUSED rlm_cache_config_t const *  config, void *  instance, request_t *  request, UNUSED void *  handle, rlm_cache_entry_t *  c  )

static

Update the TTL of an entry.

Note

handle not used except for sanity checks.

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 309 of file rlm_cache_htrie.c.

Here is the call graph for this function:

cache_heap_cmp()

static int8_t cache_heap_cmp ( void const *  one, void const *  two  )

static

Compare two entries by expiry time.

There may be multiple entries with the same expiry time.

Definition at line 164 of file rlm_cache_htrie.c.

Here is the call graph for this function:

Here is the caller graph for this function:

cache_release()

static void cache_release ( UNUSED rlm_cache_config_t const *  config, void *  instance, request_t *  request, UNUSED rlm_cache_handle_t *  handle  )

static

Release an entry unlocking any mutexes.

Note

handle not used except for sanity checks.

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 374 of file rlm_cache_htrie.c.

cf_htrie_key_parse()

static int cf_htrie_key_parse ( TALLOC_CTX *  ctx, void *  out, tmpl_rules_t const *  t_rules, CONF_ITEM *  ci, void const *  data, UNUSED call_env_parser_t const *  rule  )

static

Custom key parsing function for checking compatibility of key types.

This function does two things:

• It selects a htrie type based on the key type.
• It checks that all keys are compatible with each other.

Definition at line 94 of file rlm_cache_htrie.c.

Here is the call graph for this function:

cf_htrie_type_parse()

int cf_htrie_type_parse ( TALLOC_CTX *  ctx, void *  out, void *  parent, CONF_ITEM *  ci, conf_parser_t const *  rule  )

static

Custom htrie type parsing function.

Sets a bool, so we known if the original type was "auto", so we can constantly re-evaluate the htrie type based on the key type.

Definition at line 70 of file rlm_cache_htrie.c.

Here is the call graph for this function:

mod_detach()

static int mod_detach ( module_detach_ctx_t const *  mctx )

static

Cleanup a cache_htrie instance.

Definition at line 387 of file rlm_cache_htrie.c.

Here is the call graph for this function:

mod_instantiate()

static int mod_instantiate ( module_inst_ctx_t const *  mctx )

static

Create a new cache_htrie instance.

Parameters

[in]

mctx

Data required for instantiation.

Returns

• 0 on success.
• -1 on failure.

Definition at line 415 of file rlm_cache_htrie.c.

Here is the call graph for this function:

Variable Documentation

driver_config

conf_parser_t driver_config[]

static

Initial value:

= {
        { FR_CONF_OFFSET("type", rlm_cache_htrie_t, htype), .dflt = "auto",
          .func = cf_htrie_type_parse,
          .uctx = &(cf_table_parse_ctx_t){ .table = fr_htrie_type_table, .len = &fr_htrie_type_table_len }  },
        CONF_PARSER_TERMINATOR
}

Definition at line 58 of file rlm_cache_htrie.c.

rlm_cache_htrie

rlm_cache_driver_t rlm_cache_htrie

Initial value:

= {
        .common = {
                .magic          = MODULE_MAGIC_INIT,
                .name           = "cache_htrie",
                .config         = driver_config,
                .instantiate    = mod_instantiate,
                .detach         = mod_detach,
                .inst_size      = sizeof(rlm_cache_htrie_t),
                .inst_type      = "rlm_cache_htrie_t",
        },
        .alloc          = cache_entry_alloc,
 
        .find           = cache_entry_find,
        .insert         = cache_entry_insert,
        .expire         = cache_entry_expire,
        .set_ttl        = cache_entry_set_ttl,
        .count          = cache_entry_count,
 
        .acquire        = cache_acquire,
        .release        = cache_release,
 
        .key_parse      = cf_htrie_key_parse
}

Definition at line 450 of file rlm_cache_htrie.c.