rlm_cache_rbtree.c File Reference

Simple rbtree 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 "../../rlm_cache.h"

Include dependency graph for rlm_cache_rbtree.c:

Go to the source code of this file.

Data Structures
struct	rlm_cache_rb_entry_t
struct	rlm_cache_rbtree_t

Functions
static int	cache_acquire (void **handle, UNUSED rlm_cache_config_t const *config, void *instance, request_t *request)
	Lock the rbtree. 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 int8_t	cache_entry_cmp (void const *one, void const *two)
	Compare two entries by key. 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	mod_detach (module_detach_ctx_t const *mctx)
	Cleanup a cache_rbtree instance. More...
static int	mod_instantiate (module_inst_ctx_t const *mctx)
	Create a new cache_rbtree instance. More...

Variables
rlm_cache_driver_t	rlm_cache_rbtree

Detailed Description

Simple rbtree based cache.

Id

4838e824d1fc721f0f4f478f972840bcb0898121

Copyright

2014 The FreeRADIUS server project

Definition in file rlm_cache_rbtree.c.

---

Data Structure Documentation

rlm_cache_rb_entry_t

struct rlm_cache_rb_entry_t

Definition at line 37 of file rlm_cache_rbtree.c.

Collaboration diagram for rlm_cache_rb_entry_t:

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

rlm_cache_rbtree_t

struct rlm_cache_rbtree_t

Definition at line 30 of file rlm_cache_rbtree.c.

Collaboration diagram for rlm_cache_rbtree_t:

Data Fields
fr_rb_tree_t *	cache	Tree for looking up cache keys.
fr_heap_t *	heap	For managing entry expiry.
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 rbtree.

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 312 of file rlm_cache_rbtree.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 135 of file rlm_cache_rbtree.c.

cache_entry_cmp()

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

static

Compare two entries by key.

There may only be one entry with the same key.

Definition at line 48 of file rlm_cache_rbtree.c.

Here is the caller graph for this function:

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 296 of file rlm_cache_rbtree.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 197 of file rlm_cache_rbtree.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 155 of file rlm_cache_rbtree.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 225 of file rlm_cache_rbtree.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 267 of file rlm_cache_rbtree.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 60 of file rlm_cache_rbtree.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 332 of file rlm_cache_rbtree.c.

mod_detach()

static int mod_detach ( module_detach_ctx_t const *  mctx )

static

Cleanup a cache_rbtree instance.

Definition at line 70 of file rlm_cache_rbtree.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_rbtree instance.

Parameters

[in]

mctx

Data required for instantiation.

Returns

• 0 on success.
• -1 on failure.

Definition at line 98 of file rlm_cache_rbtree.c.

Here is the call graph for this function:

Variable Documentation

rlm_cache_rbtree

rlm_cache_driver_t rlm_cache_rbtree

Initial value:

= {
        .common = {
                .magic          = MODULE_MAGIC_INIT,
                .name           = "cache_rbtree",
                .instantiate    = mod_instantiate,
                .detach         = mod_detach,
                .inst_size      = sizeof(rlm_cache_rbtree_t),
                .inst_type      = "rlm_cache_rbtree_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,
}

Definition at line 343 of file rlm_cache_rbtree.c.