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.

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

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

owner	the owning list this dsh belongs on, or NULL if standalone
buffer_size	the allocation in bytes
count_kinds	how 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

pdsh	pointer 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

dsh	the dsh tracking the allocation
kind	the kind of allocation
src1	the first source data to copy
size1	the size of the first source data
src2	the second source data to copy (after the first), or NULL
size2	the 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

obj	a 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

dsh	the dsh
kind	the kind of allocation (0 +)
len	length 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

dsh	the dsh tracking the allocation
kind	the kind of allocation
obj	pointer to a void * to be set to the payload
size	set 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

dsh	the dsh to dump
desc	text that appears at the top of the dump

Useful information for debugging lws_dsh