Cache supporting expiry

Data Structures
struct	lws_cache_match
struct	lws_cache_results
struct	lws_cache_creation_info
union	lws_cache_creation_info::[union].u
struct	lws_cache_creation_info::[struct].u.nscookiejar
struct	lws_cache_creation_info::[struct].u.blob
struct	lws_cache_ops

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 void	lws_cache_lock (struct lws_cache_ttl_lru *cache)
LWS_VISIBLE LWS_EXTERN void	lws_cache_unlock (struct lws_cache_ttl_lru *cache)
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 *specific_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 LWS_EXTERN_FOR_DATA const struct lws_cache_ops	lws_cache_ops_heap
LWS_VISIBLE LWS_EXTERN_FOR_DATA const struct lws_cache_ops	lws_cache_ops_nscookiejar
LWS_VISIBLE LWS_EXTERN_FOR_DATA const struct lws_cache_ops	lws_cache_ops_blob

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.

The apis are threadsafe with LWS_MAX_SMP > 1: each call holds the lock of the cache and the levels chained to it while it works. But then another service thread may also destroy an item as soon as the call that gave you a pointer into the cache returns. If you use pointers from lws_cache_item_get() or lws_cache_lookup() after the call, and other threads may use the same cache, hold lws_cache_lock() over the call and your use of the pointer.

---

Data Structure Documentation

lws_cache_match

struct lws_cache_match

Definition at line 111 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 230 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::[union].u

union lws_cache_creation_info::[union].u

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

Collaboration diagram for lws_cache_creation_info::[union].u:

Data Fields
struct	nscookiejar
struct	blob

lws_cache_creation_info::[struct].u.nscookiejar

struct lws_cache_creation_info::[struct].u.nscookiejar

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

Collaboration diagram for lws_cache_creation_info::[struct].u.nscookiejar:

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

lws_cache_creation_info::[struct].u.blob

struct lws_cache_creation_info::[struct].u.blob

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

Collaboration diagram for lws_cache_creation_info::[struct].u.blob:

Data Fields
const char *	dir	the directory to store the hashed blob files in

Typedef Documentation

lws_cache_match_t

typedef struct lws_cache_match lws_cache_match_t

#include <lws-cache-ttl.h>

lws_cache_results_t

typedef struct lws_cache_results lws_cache_results_t

#include <lws-cache-ttl.h>

lws_cache_item_destroy_cb

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

#include <lws-cache-ttl.h>

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

Function Documentation

lws_cache_lock()

LWS_VISIBLE LWS_EXTERN void lws_cache_lock

(

struct lws_cache_ttl_lru *

cache

)

#include <lws-cache-ttl.h>

lws_cache_lock() - hold the lock of a cache and the levels chained to it

Parameters

cache

any level of the cache

Only needed to keep pointers into the cache valid while using them when other service threads may use the same cache (LWS_MAX_SMP > 1). The lock may be taken again by the same thread, eg, by calling the cache apis while holding it. Don't take other locks, or call apis that might, while holding it. Without SMP it has no locking effect.

References LWS_EXTERN, and LWS_VISIBLE.

lws_cache_unlock()

LWS_VISIBLE LWS_EXTERN void lws_cache_unlock

(

struct lws_cache_ttl_lru *

cache

)

#include <lws-cache-ttl.h>

lws_cache_unlock() - release the lock taken by lws_cache_lock()

Parameters

cache

the same level given to lws_cache_lock()

References LWS_EXTERN, and LWS_VISIBLE.

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 <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, in the time of the cache's service thread (info.tsi): that is lws_now_usecs() unless the app gives the time with lws_service_set_now()
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 <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.

The results pointer is only valid until the next call on the cache: getting a listed item that is not in L1 writes it there, which may evict the result set itself, or an item it names, which also destroys the result set. So copy the results before getting the items they list.

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

References LWS_EXTERN, and LWS_VISIBLE.

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 <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.

References LWS_EXTERN, and LWS_VISIBLE.

lws_cache_item_remove()

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

#include <lws-cache-ttl.h>

lws_cache_item_remove() - remove item from all cache levels

Parameters

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

Removes any copy of the item with the key specific_key from any cache level in one step. The key is matched literally at every level: wildcard characters in it have no special meaning, only lws_cache_lookup() takes wildcards.

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

References LWS_EXTERN, and LWS_VISIBLE.

lws_cache_footprint()

LWS_VISIBLE LWS_EXTERN uint64_t lws_cache_footprint

(

struct lws_cache_ttl_lru *

cache

)

#include <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

References LWS_EXTERN, and LWS_VISIBLE.

lws_cache_debug_dump()

LWS_VISIBLE LWS_EXTERN void lws_cache_debug_dump

(

struct lws_cache_ttl_lru *

cache

)

#include <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 <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 <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

References LWS_EXTERN, and LWS_VISIBLE.

lws_cache_destroy()

LWS_VISIBLE LWS_EXTERN void lws_cache_destroy

(

struct lws_cache_ttl_lru **

cache

)

#include <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.

References LWS_EXTERN, and LWS_VISIBLE.

lws_cache_expunge()

LWS_VISIBLE LWS_EXTERN int lws_cache_expunge

(

struct lws_cache_ttl_lru *

cache

)

#include <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_heap

LWS_VISIBLE LWS_EXTERN_FOR_DATA const struct lws_cache_ops lws_cache_ops_heap

#include <lws-cache-ttl.h>

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

lws_cache_ops_nscookiejar

LWS_VISIBLE LWS_EXTERN_FOR_DATA const struct lws_cache_ops lws_cache_ops_nscookiejar

#include <lws-cache-ttl.h>

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

lws_cache_ops_blob

LWS_VISIBLE LWS_EXTERN_FOR_DATA const struct lws_cache_ops lws_cache_ops_blob

#include <lws-cache-ttl.h>

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