lws-ring.h

/*
 * libwebsockets - small server side websockets and web server implementation
 *
 * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
 *
 * 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.
 */
 
struct lws_ring;
 
LWS_VISIBLE LWS_EXTERN struct lws_ring *
lws_ring_create(size_t element_len, size_t count,
                void (*destroy_element)(void *element));
 
LWS_VISIBLE LWS_EXTERN void
lws_ring_destroy(struct lws_ring *ring);
 
LWS_VISIBLE LWS_EXTERN size_t
lws_ring_get_count_free_elements(struct lws_ring *ring);
 
LWS_VISIBLE LWS_EXTERN size_t
lws_ring_get_count_waiting_elements(struct lws_ring *ring, uint32_t *tail);
 
LWS_VISIBLE LWS_EXTERN size_t
lws_ring_insert(struct lws_ring *ring, const void *src, size_t max_count);
 
LWS_VISIBLE LWS_EXTERN size_t
lws_ring_consume(struct lws_ring *ring, uint32_t *tail, void *dest,
                 size_t max_count);
 
LWS_VISIBLE LWS_EXTERN const void *
lws_ring_get_element(struct lws_ring *ring, uint32_t *tail);
 
LWS_VISIBLE LWS_EXTERN void
lws_ring_update_oldest_tail(struct lws_ring *ring, uint32_t tail);
 
LWS_VISIBLE LWS_EXTERN uint32_t
lws_ring_get_oldest_tail(struct lws_ring *ring);
 
LWS_VISIBLE LWS_EXTERN int
lws_ring_next_linear_insert_range(struct lws_ring *ring, void **start,
                                  size_t *bytes);
 
LWS_VISIBLE LWS_EXTERN void
lws_ring_bump_head(struct lws_ring *ring, size_t bytes);
 
LWS_VISIBLE LWS_EXTERN void
lws_ring_dump(struct lws_ring *ring, uint32_t *tail);
 
/*
 * This is a helper that combines the common pattern of needing to consume
 * some ringbuffer elements, move the consumer tail on, and check if that
 * has moved any ringbuffer elements out of scope, because it was the last
 * consumer that had not already consumed them.
 *
 * Elements that go out of scope because the oldest tail is now after them
 * get garbage-collected by calling the destroy_element callback on them
 * defined when the ringbuffer was created.
 */
 
#define lws_ring_consume_and_update_oldest_tail(\
                ___ring,    /* the lws_ring object */ \
                ___type,    /* type of objects with tails */ \
                ___ptail,   /* ptr to tail of obj with tail doing consuming */ \
                ___count,   /* count of payload objects being consumed */ \
                ___list_head,   /* head of list of objects with tails */ \
                ___mtail,   /* member name of tail in ___type */ \
                ___mlist  /* member name of next list member ptr in ___type */ \
        ) { \
                int ___n, ___m; \
        \
        ___n = lws_ring_get_oldest_tail(___ring) == *(___ptail); \
        lws_ring_consume(___ring, ___ptail, NULL, ___count); \
        if (___n) { \
                uint32_t ___oldest; \
                ___n = 0; \
                ___oldest = *(___ptail); \
                lws_start_foreach_llp(___type **, ___ppss, ___list_head) { \
                        ___m = (int)lws_ring_get_count_waiting_elements( \
                                        ___ring, &(*___ppss)->___mtail); \
                        if (___m >= ___n) { \
                                ___n = ___m; \
                                ___oldest = (*___ppss)->___mtail; \
                        } \
                } lws_end_foreach_llp(___ppss, ___mlist); \
        \
                lws_ring_update_oldest_tail(___ring, ___oldest); \
        } \
}
 
/*
 * This does the same as the lws_ring_consume_and_update_oldest_tail()
 * helper, but for the simpler case there is only one consumer, so one
 * tail, and that tail is always the oldest tail.
 */
 
#define lws_ring_consume_single_tail(\
                ___ring,  /* the lws_ring object */ \
                ___ptail, /* ptr to tail of obj with tail doing consuming */ \
                ___count  /* count of payload objects being consumed */ \
        ) { \
        lws_ring_consume(___ring, ___ptail, NULL, ___count); \
        lws_ring_update_oldest_tail(___ring, *(___ptail)); \
}