Lightweight C library for HTML5 websockets
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


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)


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)


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

◆ lws_cache_results_t

◆ 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

cachethe existing cache to allocate the object in
specific_keya key string that identifies the item in the cache
sourceoptional payload for the cached item, NULL means caller will write the payload
sizethe size of the object to allocate
expirythe usec time that the object will autodestroy
ppayNULL, 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

cachethe cache to search for the key
wildcard_keythe item key string, may contain wildcards
pdatapointer to pointer to be set to the serialized result list
psizepointer 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

cachethe cache to search for the key
specific_keythe key string of the item to get
pdatapointer to a void * to be set to the payload in L1 cache
psizepointer 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

cachethe cache to search for the key
wildcard_keythe 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

cachecache 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

cachecache 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

walk_ctxthe 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

infoa 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

cachepointer 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

cachepointer 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