/* * libwebsockets - small server side websockets and web server implementation * * Copyright (C) 2010 - 2019 Andy Green * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to * deal in the Software without restriction, including without limitation the * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or * sell copies of the Software, and to permit persons to whom the Software is * furnished to do so, subject to the following conditions: * * The above copyright notice and this permission notice shall be included in * all copies or substantial portions of the Software. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS * IN THE SOFTWARE. */ /* * lws_dsh (Disordered Shared Heap) is an opaque abstraction supporting a single * linear buffer (overallocated at end of the lws_dsh_t) which may contain * multiple kinds of packets that are retired out of order, and tracked by kind. * * Each kind of packet has an lws_dll2 list of its kind of packets and acts as * a FIFO; packets of a particular type are always retired in order. But there * is no requirement about the order types are retired matching the original * order they arrived. * * Gaps are tracked as just another kind of "packet" list. * * "allocations" (including gaps) are prepended by an lws_dsh_object_t. * * dsh may themselves be on an lws_dll2_owner list, and under memory pressure * allocate into other buffers on the list. * * All management structures exist inside the allocated buffer. */ enum { LWS_DSHFLAG_ENABLE_COALESCE = (1u << 24), LWS_DSHFLAG_ENABLE_SPLIT = (1u << 25), }; /** * lws_dsh_create() - Allocate a DSH buffer * * \param owner: the owning list this dsh belongs on, or NULL if standalone * \param buffer_size: the allocation in bytes * \param 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_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_dsh_destroy() - Destroy a DSH buffer * * \param 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_VISIBLE LWS_EXTERN void lws_dsh_destroy(struct lws_dsh **pdsh); /** * lws_dsh_alloc_tail() - make a suballocation inside a dsh * * \param dsh: the dsh tracking the allocation * \param kind: the kind of allocation * \param src1: the first source data to copy * \param size1: the size of the first source data * \param src2: the second source data to copy (after the first), or NULL * \param 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_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_free() - free a suballocation from the dsh * * \param obj: a pointer to a void * that pointed to the allocated payload * * This returns the space used by \p obj in the dsh buffer to the free list * of the dsh the allocation came from. */ LWS_VISIBLE LWS_EXTERN void lws_dsh_free(void **obj); /** * lws_dsh_consume() - partially consume a dsh * * \param dsh: the dsh * \param kind: the kind of allocation (0 +) * \param len: length to consume * * Consume part of a dsh object. */ 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_dsh_get_head() - get the head allocation inside the dsh * * \param dsh: the dsh tracking the allocation * \param kind: the kind of allocation * \param obj: pointer to a void * to be set to the payload * \param 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_VISIBLE LWS_EXTERN int lws_dsh_get_head(struct lws_dsh *dsh, int kind, void **obj, size_t *size); /** * lws_dsh_describe() - DEBUG BUILDS ONLY dump the dsh to the logs * * \param dsh: the dsh to dump * \param desc: text that appears at the top of the dump * * Useful information for debugging lws_dsh */ LWS_VISIBLE LWS_EXTERN void lws_dsh_describe(struct lws_dsh *dsh, const char *desc);