Cache supporting expiry

Data Structures
struct	lws_cache_match
struct	lws_cache_results
struct	lws_cache_creation_info
struct	lws_cache_ops
union	lws_cache_creation_info.u
struct	lws_cache_creation_info.u.nscookiejar

Typedefs
typedef struct lws_cache_match	lws_cache_match_t
typedef struct lws_cache_results	lws_cache_results_t
typedef void(*	lws_cache_item_destroy_cb) (void *item, size_t size)

Functions
LWS_VISIBLE LWS_EXTERN int	lws_cache_write_through (struct lws_cache_ttl_lru *cache, const char *specific_key, const uint8_t *source, size_t size, lws_usec_t expiry, void **ppay)
LWS_VISIBLE LWS_EXTERN int	lws_cache_lookup (struct lws_cache_ttl_lru *cache, const char *wildcard_key, const void **pdata, size_t *psize)
LWS_VISIBLE LWS_EXTERN int	lws_cache_item_get (struct lws_cache_ttl_lru *cache, const char *specific_key, const void **pdata, size_t *psize)
LWS_VISIBLE LWS_EXTERN int	lws_cache_item_remove (struct lws_cache_ttl_lru *cache, const char *wildcard_key)
LWS_VISIBLE LWS_EXTERN uint64_t	lws_cache_footprint (struct lws_cache_ttl_lru *cache)
LWS_VISIBLE LWS_EXTERN void	lws_cache_debug_dump (struct lws_cache_ttl_lru *cache)
LWS_VISIBLE LWS_EXTERN int	lws_cache_results_walk (lws_cache_results_t *walk_ctx)
LWS_VISIBLE LWS_EXTERN struct lws_cache_ttl_lru *	lws_cache_create (const struct lws_cache_creation_info *info)
LWS_VISIBLE LWS_EXTERN void	lws_cache_destroy (struct lws_cache_ttl_lru **cache)
LWS_VISIBLE LWS_EXTERN int	lws_cache_expunge (struct lws_cache_ttl_lru *cache)

Variables
LWS_VISIBLE const struct lws_cache_ops lws_cache_ops_heap	lws_cache_ops_nscookiejar

Detailed Description

Cache supporting expiry

These apis let you quickly and reliably implement caches of named objects, that have a "destroy-by date" and cache limits that will be observed.

You can instantiate as many caches as you need. The first one must be an L1 / heap cache type, it can have parents and grandparents of other types which are accessible why writing / looking up and getting from the L1 cache. The outer "cache" layer may persistently store items to a backing store.

Allocated object memory is entirely for the use of user code, up to the requested size.

The key name for the listed objects may be any string chosen by the user, there is no special length limit as it is also allocated.

Both expiry and LRU orderings are kept so it is easy to find out usage ordering and when the next object that will expire.

Cached objects may be destroyed any time you go around the event loop, when you allocate new objects (to keep the whole cache under the specified limit), or when their expiry time arrives. So you shouldn't keep copies of pointers to cached objects after returning to the event loop.

---

Data Structure Documentation

lws_cache_match

struct lws_cache_match

Definition at line 79 of file lws-cache-ttl.h.

Collaboration diagram for lws_cache_match:

Data Fields
lws_dll2_t	list
lws_usec_t	expiry
size_t	payload_size	the payload is not attached here. This is a hint about what (*get)() will return for this tag name.
size_t	tag_size

lws_cache_results

struct lws_cache_results

Definition at line 191 of file lws-cache-ttl.h.

Collaboration diagram for lws_cache_results:

Data Fields
const uint8_t *	ptr
size_t	size
size_t	payload_len
size_t	tag_len
const uint8_t *	tag

lws_cache_creation_info

struct lws_cache_creation_info

Definition at line 220 of file lws-cache-ttl.h.

Collaboration diagram for lws_cache_creation_info:

Data Fields
struct lws_context *	cx	Mandatory: the lws_context
const char *	name	Mandatory: short cache name
lws_cache_item_destroy_cb	cb	NULL, or a callback that can hook cache item destory
struct lws_cache_ttl_lru *	parent	NULL, or next cache level
const struct lws_cache_ops *	ops	NULL for default, heap-based ops, else custom cache storage and query implementation
union lws_cache_creation_info	u	these are extra configuration for specific cache types
size_t	max_footprint	0, or the max heap allocation allowed before destroying lru items to keep it under the limit
size_t	max_items	0, or the max number of items allowed in the cache before destroying lru items to keep it under the limit
size_t	max_payload	0, or the max allowed payload size for one item
int	tsi	0 unless using SMP, then tsi to bind sul to

lws_cache_creation_info.u

union lws_cache_creation_info.u

Definition at line 233 of file lws-cache-ttl.h.

Collaboration diagram for lws_cache_creation_info.u:

Data Fields
u	nscookiejar

lws_cache_creation_info.u.nscookiejar

struct lws_cache_creation_info.u.nscookiejar

Definition at line 234 of file lws-cache-ttl.h.

Collaboration diagram for lws_cache_creation_info.u.nscookiejar:

Data Fields
const char *	filepath	the filepath to store items in

Typedef Documentation

lws_cache_match_t

typedef struct lws_cache_match lws_cache_match_t

#include <include/libwebsockets/lws-cache-ttl.h>

lws_cache_results_t

typedef struct lws_cache_results lws_cache_results_t

#include <include/libwebsockets/lws-cache-ttl.h>

lws_cache_item_destroy_cb

typedef void(* lws_cache_item_destroy_cb) (void *item, size_t size)

#include <include/libwebsockets/lws-cache-ttl.h>

Definition at line 219 of file lws-cache-ttl.h.

Function Documentation

lws_cache_write_through()

LWS_VISIBLE LWS_EXTERN int lws_cache_write_through	(	struct lws_cache_ttl_lru *	cache,
		const char *	specific_key,
		const uint8_t *	source,
		size_t	size,
		lws_usec_t	expiry,
		void **	ppay
	)

#include <include/libwebsockets/lws-cache-ttl.h>

lws_cache_write_through() - add a new cache item object in all layers

Parameters

cache	the existing cache to allocate the object in
specific_key	a key string that identifies the item in the cache
source	optional payload for the cached item, NULL means caller will write the payload
size	the size of the object to allocate
expiry	the usec time that the object will autodestroy
ppay	NULL, or a pointer to a void * to be set to the L1 payload

If an item with the key already exists, it is destroyed before allocating a new one.

Returns 0 if successful. The written entry will be scheduled to be auto- destroyed when expiry occurs.

Adding or removing cache items may cause invalidation of cached queries.

lws_cache_lookup()

LWS_VISIBLE LWS_EXTERN int lws_cache_lookup	(	struct lws_cache_ttl_lru *	cache,
		const char *	wildcard_key,
		const void **	pdata,
		size_t *	psize
	)

#include <include/libwebsockets/lws-cache-ttl.h>

lws_cache_heap_lookup() - get a list of matching items

Parameters

cache	the cache to search for the key
wildcard_key	the item key string, may contain wildcards
pdata	pointer to pointer to be set to the serialized result list
psize	pointer to size_t to receive length of serialized result list

This finds all unique items in the final cache that match search_key, which may contain wildcards. It does not return the payloads for matching items, just a list of specific tags in the that match.

If successful, results are provided in a serialized list format, in no particular order, each result has the following fields

• BE32: payload size in bytes (payload itself is not included)
• BE32: specific tag name length in bytes
• chars: tag name with terminating NUL

These serialized results are themselves cached in L1 cache (only) and the result pointers are set pointing into that. If the results are still in L1 cache next time this api is called, the results will be returned directly from that without repeating the expensive lookup on the backup store. That is why the results are provided in serialized form.

The cached results list expiry is set to the earliest expiry of any listed item. Additionally any cached results are invalidated on addition or deletion (update is done as addition + deletion) of any item that would match the results' original wildcard_key. For the typical case new items are rare compared to lookups, this is efficient.

Lookup matching does not itself affect LRU or cache status of the result itsems. Typically user code will get the lookup results, and then perform get operations on each item in its desired order, that will bring the items to the head of the LRU list and occupy L1 cache.

Returns 0 if proceeded alright, or nonzero if error. If there was an error, any partial results set has been deallocated cleanly before returning.

lws_cache_item_get()

LWS_VISIBLE LWS_EXTERN int lws_cache_item_get	(	struct lws_cache_ttl_lru *	cache,
		const char *	specific_key,
		const void **	pdata,
		size_t *	psize
	)

#include <include/libwebsockets/lws-cache-ttl.h>

lws_cache_item_get() - bring a specific item into L1 and get payload info

Parameters

cache	the cache to search for the key
specific_key	the key string of the item to get
pdata	pointer to a void * to be set to the payload in L1 cache
psize	pointer to a size_t to be set to the payload size

If the cache still has an item matching the key string, it will be destroyed.

Adding or removing cache items may cause invalidation of cached queries.

Notice the cache payload is a blob of the given size. If you are storing strings, there is no NUL termination unless you stored them with it.

Returns 0 if successful.

lws_cache_item_remove()

LWS_VISIBLE LWS_EXTERN int lws_cache_item_remove	(	struct lws_cache_ttl_lru *	cache,
		const char *	wildcard_key
	)

#include <include/libwebsockets/lws-cache-ttl.h>

lws_cache_item_remove() - remove item from all cache levels

Parameters

cache	the cache to search for the key
wildcard_key	the item key string

Removes any copy of any item matching the wildcard_key from any cache level in one step.

Adding or removing cache items may cause invalidation of cached queries that could refer to the removed item.

lws_cache_footprint()

LWS_VISIBLE LWS_EXTERN uint64_t lws_cache_footprint

(

struct lws_cache_ttl_lru *

cache

)

#include <include/libwebsockets/lws-cache-ttl.h>

lws_cache_footprint() - query the amount of storage used by the cache layer

Parameters

cache

cache to query

Returns number of payload bytes stored in cache currently

lws_cache_debug_dump()

LWS_VISIBLE LWS_EXTERN void lws_cache_debug_dump

(

struct lws_cache_ttl_lru *

cache

)

#include <include/libwebsockets/lws-cache-ttl.h>

lws_cache_debug_dump() - if built in debug mode dump cache contents to log

Parameters

cache

cache to dump

If lws was built in debug mode, dump cache to log, otherwise a NOP.

lws_cache_results_walk()

LWS_VISIBLE LWS_EXTERN int lws_cache_results_walk

(

lws_cache_results_t *

walk_ctx

)

#include <include/libwebsockets/lws-cache-ttl.h>

lws_cache_results_walk() - parse next result

Parameters

walk_ctx

the context of the results blob to walk

Caller must initialize walk_ctx.ptr and walk_ctx.size before calling. These are set to the results returned from a _lookup api call.

The call returns 0 if the struct elements have been set to a result, or 1 if there where no more results in the blob to walk.

If successful, after the call payload_len is set to the length of the payload related to this result key (the payload itself is not present), tag_len is set to the length of the result key name, and tag is set to the result tag name, with a terminating NUL.

lws_cache_create()

LWS_VISIBLE LWS_EXTERN struct lws_cache_ttl_lru* lws_cache_create

(

const struct lws_cache_creation_info *

info

)

#include <include/libwebsockets/lws-cache-ttl.h>

lws_cache_create() - create an empty cache you can allocate items in

Parameters

info	a struct describing the cache to create

Create an empty cache you can allocate items in. The cache will be kept below the max_footprint and max_items limits if they are nonzero, by destroying least-recently-used items until it remains below the limits.

Items will auto-destroy when their expiry time is reached.

When items are destroyed from the cache, if cb is non-NULL, it will be called back with the item pointer after it has been removed from the cache, but before it is deallocated and destroyed.

context and tsi are used when scheduling expiry callbacks

lws_cache_destroy()

LWS_VISIBLE LWS_EXTERN void lws_cache_destroy

(

struct lws_cache_ttl_lru **

cache

)

#include <include/libwebsockets/lws-cache-ttl.h>

lws_cache_destroy() - destroy a previously created cache

Parameters

cache

pointer to the cache

Everything in the cache is destroyed, then the cache itself is destroyed, and *cache set to NULL.

lws_cache_expunge()

LWS_VISIBLE LWS_EXTERN int lws_cache_expunge

(

struct lws_cache_ttl_lru *

cache

)

#include <include/libwebsockets/lws-cache-ttl.h>

lws_cache_expunge() - destroy all items in cache and parents

Parameters

cache

pointer to the cache

Everything in the cache and parents is destroyed, leaving it empty. If the cache has a backing store, it is deleted.

Returns 0 if no problems reported at any cache layer, else nonzero.

Variable Documentation

lws_cache_ops_nscookiejar

LWS_VISIBLE const struct lws_cache_ops lws_cache_ops_heap lws_cache_ops_nscookiejar

extern

#include <include/libwebsockets/lws-cache-ttl.h>