libwebsockets
Lightweight C library for HTML5 websockets
lws-dsh.h File Reference
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Enumerations

enum  { LWS_DSHFLAG_ENABLE_COALESCE = (1u << 24) , LWS_DSHFLAG_ENABLE_SPLIT = (1u << 25) }
 

Functions

LWS_VISIBLE LWS_EXTERN struct lws_dsh * lws_dsh_create (lws_dll2_owner_t *owner, size_t buffer_size, int count_kinds)
 
LWS_VISIBLE LWS_EXTERN void lws_dsh_empty (struct lws_dsh *dsh)
 
LWS_VISIBLE LWS_EXTERN void lws_dsh_destroy (struct lws_dsh **pdsh)
 
LWS_VISIBLE LWS_EXTERN int lws_dsh_alloc_tail (struct lws_dsh *dsh, int kind, const void *src1, size_t size1, const void *src2, size_t size2)
 
LWS_VISIBLE LWS_EXTERN void lws_dsh_free (void **obj)
 
LWS_VISIBLE LWS_EXTERN void lws_dsh_consume (struct lws_dsh *dsh, int kind, size_t len)
 
LWS_VISIBLE LWS_EXTERN size_t lws_dsh_get_size (struct lws_dsh *dsh, int kind)
 
LWS_VISIBLE LWS_EXTERN int lws_dsh_get_head (struct lws_dsh *dsh, int kind, void **obj, size_t *size)
 
LWS_VISIBLE LWS_EXTERN void lws_dsh_describe (struct lws_dsh *dsh, const char *desc)
 

Enumeration Type Documentation

◆ anonymous enum

anonymous enum
Enumerator
LWS_DSHFLAG_ENABLE_COALESCE 
LWS_DSHFLAG_ENABLE_SPLIT 

Definition at line 45 of file lws-dsh.h.

45 {
46 LWS_DSHFLAG_ENABLE_COALESCE = (1u << 24),
47 LWS_DSHFLAG_ENABLE_SPLIT = (1u << 25),
48};
@ LWS_DSHFLAG_ENABLE_SPLIT
Definition: lws-dsh.h:47
@ LWS_DSHFLAG_ENABLE_COALESCE
Definition: lws-dsh.h:46

Function Documentation

◆ lws_dsh_create()

LWS_VISIBLE LWS_EXTERN struct lws_dsh * lws_dsh_create ( lws_dll2_owner_t owner,
size_t  buffer_size,
int  count_kinds 
)

lws_dsh_create() - Allocate a DSH buffer

Parameters
ownerthe owning list this dsh belongs on, or NULL if standalone
buffer_sizethe allocation in bytes
count_kindshow many separately-tracked fifos use the buffer, or-ed with optional LWS_DSHFLAGs

This makes a single heap allocation that includes internal tracking objects in the buffer. Sub-allocated objects are bound to a "kind" index and managed via a FIFO for each kind.

Every "kind" of allocation shares the same buffer space.

Multiple buffers may be bound together in an lws_dll2 list, and if an allocation cannot be satisfied by the local buffer, space can be borrowed from other dsh in the same list (the local dsh FIFO tracks these "foreign" allocations as if they were local).

Returns an opaque pointer to the dsh, or NULL if allocation failed.

◆ lws_dsh_empty()

LWS_VISIBLE LWS_EXTERN void lws_dsh_empty ( struct lws_dsh *  dsh)

◆ lws_dsh_destroy()

LWS_VISIBLE LWS_EXTERN void lws_dsh_destroy ( struct lws_dsh **  pdsh)

lws_dsh_destroy() - Destroy a DSH buffer

Parameters
pdshpointer to the dsh pointer

Deallocates the DSH and sets *pdsh to NULL.

Before destruction, any foreign buffer usage on the part of this dsh are individually freed. All dsh on the same list are walked and checked if they have their own foreign allocations on the dsh buffer being destroyed. If so, it attempts to migrate the allocation to a dsh that is not currently being destroyed. If all else fails (basically the buffer memory is being shrunk) unmigratable objects are cleanly destroyed.

◆ lws_dsh_alloc_tail()

LWS_VISIBLE LWS_EXTERN int lws_dsh_alloc_tail ( struct lws_dsh *  dsh,
int  kind,
const void *  src1,
size_t  size1,
const void *  src2,
size_t  size2 
)

lws_dsh_alloc_tail() - make a suballocation inside a dsh

Parameters
dshthe dsh tracking the allocation
kindthe kind of allocation
src1the first source data to copy
size1the size of the first source data
src2the second source data to copy (after the first), or NULL
size2the size of the second source data

Allocates size1 + size2 bytes in a dsh (it prefers the given dsh but will borrow space from other dsh on the same list if necessary) and copies size1 bytes into it from src1, followed by size2 bytes from src2 if src2 isn't NULL. The actual suballocation is a bit larger because of alignment and a prepended management header.

The suballocation is added to the kind-specific FIFO at the tail.

◆ lws_dsh_free()

LWS_VISIBLE LWS_EXTERN void lws_dsh_free ( void **  obj)

lws_dsh_free() - free a suballocation from the dsh

Parameters
obja pointer to a void * that pointed to the allocated payload

This returns the space used by obj in the dsh buffer to the free list of the dsh the allocation came from.

◆ lws_dsh_consume()

LWS_VISIBLE LWS_EXTERN void lws_dsh_consume ( struct lws_dsh *  dsh,
int  kind,
size_t  len 
)

lws_dsh_consume() - partially consume a dsh

Parameters
dshthe dsh
kindthe kind of allocation (0 +)
lenlength to consume

Consume part of a dsh object.

◆ lws_dsh_get_size()

LWS_VISIBLE LWS_EXTERN size_t lws_dsh_get_size ( struct lws_dsh *  dsh,
int  kind 
)

◆ lws_dsh_get_head()

LWS_VISIBLE LWS_EXTERN int lws_dsh_get_head ( struct lws_dsh *  dsh,
int  kind,
void **  obj,
size_t *  size 
)

lws_dsh_get_head() - get the head allocation inside the dsh

Parameters
dshthe dsh tracking the allocation
kindthe kind of allocation
objpointer to a void * to be set to the payload
sizeset to the size of the allocation

This gets the "next" object in the kind FIFO for the dsh, and returns 0 if any. If none, returns nonzero.

This is nondestructive of the fifo or the payload. Use lws_dsh_free on obj to remove the entry from the kind fifo and return the payload to the free list.

◆ lws_dsh_describe()

LWS_VISIBLE LWS_EXTERN void lws_dsh_describe ( struct lws_dsh *  dsh,
const char *  desc 
)

lws_dsh_describe() - DEBUG BUILDS ONLY dump the dsh to the logs

Parameters
dshthe dsh to dump
desctext that appears at the top of the dump

Useful information for debugging lws_dsh