All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Data Structures | Macros | Typedefs | Enumerations
rlm_cache.h File Reference
#include <freeradius-devel/radiusd.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  cache_driver
 
struct  rlm_cache_config_t
 Configuration for the rlm_cache module. More...
 
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 *driver_inst, REQUEST *request)
 Acquire a handle to access the cache. More...
 
typedef struct cache_driver cache_driver_t
 
typedef rlm_cache_entry_t *(* cache_entry_alloc_t )(rlm_cache_config_t const *conf, void *driver_inst, REQUEST *request)
 Allocate a new cache entry. More...
 
typedef uint32_t(* cache_entry_count_t )(rlm_cache_config_t const *config, void *driver_inst, REQUEST *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 *driver_inst, REQUEST *request, void *handle, uint8_t const *key, size_t key_len)
 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 *driver_inst, REQUEST *request, void *handle, uint8_t const *key, size_t key_len)
 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 *driver_inst, REQUEST *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 *driver_inst, REQUEST *request, void *handle, rlm_cache_entry_t *c)
 Update the ttl of an entry in the cace. More...
 
typedef int(* cache_instantiate_t )(CONF_SECTION *conf, rlm_cache_config_t const *config, void *driver_inst)
 Instantiate a driver. More...
 
typedef int(* cache_reconnect_t )(rlm_cache_handle_t **handle, rlm_cache_config_t const *config, void *driver_inst, REQUEST *request)
 Reconnect a previously acquired handle. More...
 
typedef void(* cache_release_t )(rlm_cache_config_t const *config, void *driver_inst, REQUEST *request, rlm_cache_handle_t *handle)
 Release a previously acquired handle. More...
 
typedef struct rlm_cache_config_t rlm_cache_config_t
 Configuration for the rlm_cache module. More...
 
typedef struct rlm_cache_entry_t rlm_cache_entry_t
 
typedef void rlm_cache_handle_t
 
typedef struct rlm_cache_t rlm_cache_t
 

Enumerations

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

Data Structure Documentation

struct cache_driver

Definition at line 278 of file rlm_cache.h.

+ Collaboration diagram for cache_driver:
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.
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.
size_t inst_size How many bytes should be allocated for the driver's instance data.
cache_instantiate_t instantiate (optional) Instantiate a driver.
char const * name Driver name.
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.
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 47 of file rlm_cache.h.

+ Collaboration diagram for rlm_cache_config_t:
Data Fields
char const * driver_name Driver name.
int32_t epoch Time after which entries are considered valid.
vp_tmpl_t * key What to expand to get the value of the key.
uint32_t max_entries Maximum entries allowed.
char const * name Name of xlat function to register.
bool stats Generate statistics.
uint32_t ttl How long an entry is valid for.
struct rlm_cache_entry_t

Definition at line 76 of file rlm_cache.h.

+ Collaboration diagram for rlm_cache_entry_t:
Data Fields
time_t created When the entry was created.
time_t expires When the entry expires.
long long int hits How many times the entry has been retrieved.
uint8_t const * key Key used to identify entry.
size_t key_len Length of key data.
vp_map_t * maps Head of the maps list.
struct rlm_cache_t

Definition at line 64 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.
CONF_SECTION * cs
cache_driver_t * driver Driver.
void * driver_inst Driver instance data.
void * handle Driver handle.
vp_map_t * maps Attribute map applied to users.

and profiles.

Macro Definition Documentation

#define MAX_ATTRMAP   128

Definition at line 33 of file rlm_cache.h.

Typedef Documentation

typedef int(* cache_acquire_t)(void **handle, rlm_cache_config_t const *config, void *driver_inst, REQUEST *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]handleWhere to write pointer to handle to access the cache with.
[in]configfor this instance of the rlm_cache module.
[in]driver_instDriver specific instance data.
[in]requestThe current request.
Returns
  • 0 on success.
  • -1 on failure.

Definition at line 247 of file rlm_cache.h.

typedef struct cache_driver cache_driver_t

Definition at line 29 of file rlm_cache.h.

typedef rlm_cache_entry_t*(* cache_entry_alloc_t)(rlm_cache_config_t const *conf, void *driver_inst, REQUEST *request)

Allocate a new cache entry.

Definition at line 103 of file rlm_cache.h.

typedef uint32_t(* cache_entry_count_t)(rlm_cache_config_t const *config, void *driver_inst, REQUEST *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]configfor this instance of the rlm_cache module.
[in]driver_instDriver specific instance data.
[in]requestThe current request.
handlethe 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 231 of file rlm_cache.h.

typedef cache_status_t(* cache_entry_expire_t)(rlm_cache_config_t const *config, void *driver_inst, REQUEST *request, void *handle, uint8_t const *key, size_t key_len)

Remove an entry from the cache.

Note
This callback is not optional.
Parameters
[in]configfor this instance of the rlm_cache module.
[in]driver_instDriver specific instance data.
[in]requestThe current request.
[in]handlethe driver gave us when we called cache_acquire_t, or NULL if no cache_acquire_t callback was provided.
[in]keyof entry to expire.
[in]key_lenthe length of the key string.
Returns

Definition at line 193 of file rlm_cache.h.

typedef cache_status_t(* cache_entry_find_t)(rlm_cache_entry_t **out, rlm_cache_config_t const *config, void *driver_inst, REQUEST *request, void *handle, uint8_t const *key, size_t key_len)

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]outWhere to write a pointer to the retrieved entry (if there was one).
[in]configfor this instance of the rlm_cache module.
[in]driver_instDriver specific instance data.
[in]requestThe current request.
[in]handlethe driver gave us when we called cache_acquire_t, or NULL if no cache_acquire_t callback was provided.
[in]keyto use to lookup cache entry
[in]key_lenthe length of the key string.
Returns

Definition at line 141 of file rlm_cache.h.

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
centry to free.

Definition at line 116 of file rlm_cache.h.

typedef cache_status_t(* cache_entry_insert_t)(rlm_cache_config_t const *config, void *driver_inst, REQUEST *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
configfor this instance of the rlm_cache module.
driver_instDriver specific instance data.
requestThe current request.
handlethe driver gave us when we called cache_acquire_t, or NULL if no cache_acquire_t callback was provided.
cto insert.
Returns

Definition at line 172 of file rlm_cache.h.

typedef cache_status_t(* cache_entry_set_ttl_t)(rlm_cache_config_t const *config, void *driver_inst, REQUEST *request, void *handle, rlm_cache_entry_t *c)

Update the ttl of an entry in the cace.

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]configfor this instance of the rlm_cache module.
[in]driver_instDriver specific instance data.
[in]requestThe current request.
[in]handlethe driver gave us when we called cache_acquire_t, or NULL if no cache_acquire_t callback was provided.
[in]cto update the TTL of. c->ttl will have been set to the new value.
Returns

Definition at line 216 of file rlm_cache.h.

typedef int(* cache_instantiate_t)(CONF_SECTION *conf, rlm_cache_config_t const *config, void *driver_inst)

Instantiate a driver.

Function to handle any driver specific instantiation.

Parameters
confsection holding driver specific CONF_PAIR (s).
configof the rlm_cache module. Should not be modified.
driver_instA uint8_t array of inst_size if inst_size > 0, else NULL. Drivers should add their own cleanup function to this chunk using talloc_set_destructor.
Returns
  • 0 on success.
  • -1 on failure.

Definition at line 98 of file rlm_cache.h.

typedef int(* cache_reconnect_t)(rlm_cache_handle_t **handle, rlm_cache_config_t const *config, void *driver_inst, REQUEST *request)

Reconnect a previously acquired handle.

Note
This callback is optional.
Parameters
[in,out]handleto reinitialise/reconnect.
[in]configfor this instance of the rlm_cache module.
[in]driver_instDriver specific instance data.
[in]requestThe current request.
Returns
  • 0 on success.
  • -1 on failure.

Definition at line 275 of file rlm_cache.h.

typedef void(* cache_release_t)(rlm_cache_config_t const *config, void *driver_inst, REQUEST *request, rlm_cache_handle_t *handle)

Release a previously acquired handle.

Note
This callback is optional.
Parameters
[in]configfor this instance of the rlm_cache module.
[in]driver_instDriver specific instance data.
[in]requestThe current request.
[in]handleto release.

Definition at line 259 of file rlm_cache.h.

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.

typedef void rlm_cache_handle_t

Definition at line 31 of file rlm_cache.h.

typedef struct rlm_cache_t rlm_cache_t

Enumeration Type Documentation

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 35 of file rlm_cache.h.