data_buffer.c File Reference

Data Buffer API. More...

#include "asterisk.h"
#include "asterisk/logger.h"
#include "asterisk/strings.h"
#include "asterisk/data_buffer.h"
#include "asterisk/linkedlists.h"

Include dependency graph for data_buffer.c:

Go to the source code of this file.

Data Structures
struct	ast_data_buffer
	Data buffer containing fixed number of data payloads. More...
struct	data_buffer_payload_entry
	Payload entry placed inside of the data buffer list. More...

Macros
#define	CACHED_PAYLOAD_MAX   5
	The number of payloads to increment the cache by. More...

Functions
struct ast_data_buffer *	ast_data_buffer_alloc (ast_data_buffer_free_callback free_fn, size_t size)
	Allocate a data buffer. More...
static void	ast_data_buffer_cache_adjust (struct ast_data_buffer *buffer)
	Helper function that sets the cache to its maximum number of payloads. More...
size_t	ast_data_buffer_count (const struct ast_data_buffer *buffer)
	Return the number of payloads in a data buffer. More...
void	ast_data_buffer_free (struct ast_data_buffer *buffer)
	Free a data buffer (and all held data payloads) More...
void *	ast_data_buffer_get (const struct ast_data_buffer *buffer, size_t pos)
	Retrieve a data payload from the data buffer. More...
size_t	ast_data_buffer_max (const struct ast_data_buffer *buffer)
	Return the maximum number of payloads a data buffer can hold. More...
int	ast_data_buffer_put (struct ast_data_buffer *buffer, size_t pos, void *payload)
	Place a data payload at a position in the data buffer. More...
void *	ast_data_buffer_remove (struct ast_data_buffer *buffer, size_t pos)
	Remove a data payload from the data buffer. More...
void *	ast_data_buffer_remove_head (struct ast_data_buffer *buffer)
	Remove the first payload from the data buffer. More...
void	ast_data_buffer_resize (struct ast_data_buffer *buffer, size_t size)
	Resize a data buffer. More...
static void	data_buffer_free_buffer_payload (struct ast_data_buffer *buffer, struct data_buffer_payload_entry *buffer_payload)
static struct data_buffer_payload_entry *	data_buffer_payload_alloc (void *payload, size_t pos)
	Helper function to allocate a data payload. More...
static void	free_fn_do_nothing (void *data)

Detailed Description

Data Buffer API.

Author

Joshua Colp jcolp.nosp@m.@dig.nosp@m.ium.c.nosp@m.om

Ben Ford bford.nosp@m.@dig.nosp@m.ium.c.nosp@m.om

Definition in file data_buffer.c.

Macro Definition Documentation

CACHED_PAYLOAD_MAX

#define CACHED_PAYLOAD_MAX   5

The number of payloads to increment the cache by.

Definition at line 42 of file data_buffer.c.

Function Documentation

ast_data_buffer_alloc()

struct ast_data_buffer * ast_data_buffer_alloc	(	ast_data_buffer_free_callback	free_fn,
		size_t	size
	)

Allocate a data buffer.

Parameters

free_fn	Callback function to free a data payload
size	The maximum number of data payloads to contain in the data buffer

Return values

non-NULL	success
NULL	failure

Note

free_fn can be NULL. It is up to the consumer of this API to ensure that memory is managed appropriately.

Since

15.4.0

Definition at line 145 of file data_buffer.c.

{
    struct ast_data_buffer *buffer;
 
    ast_assert(size != 0);
 
    buffer = ast_calloc(1, sizeof(*buffer));
    if (!buffer) {
        return NULL;
    }
 
    AST_LIST_HEAD_INIT_NOLOCK(&buffer->payloads);
    AST_LIST_HEAD_INIT_NOLOCK(&buffer->cached_payloads);
 
    /* If free_fn is NULL, just use free_fn_do_nothing as a default */
    buffer->free_fn = free_fn ? free_fn : free_fn_do_nothing;
    buffer->max = size;
 
    ast_data_buffer_cache_adjust(buffer);
 
    return buffer;
}

References ast_assert, ast_calloc, ast_data_buffer_cache_adjust(), AST_LIST_HEAD_INIT_NOLOCK, ast_data_buffer::cached_payloads, ast_data_buffer::free_fn, free_fn_do_nothing(), ast_data_buffer::max, NULL, and ast_data_buffer::payloads.

Referenced by ast_rtp_prop_set(), and AST_TEST_DEFINE().

ast_data_buffer_cache_adjust()

static void ast_data_buffer_cache_adjust ( struct ast_data_buffer *  buffer )

static

Helper function that sets the cache to its maximum number of payloads.

Definition at line 100 of file data_buffer.c.

{
    int buffer_space;
 
    ast_assert(buffer != NULL);
 
    buffer_space = buffer->max - buffer->count;
 
    if (buffer->cache_count == buffer_space) {
        return;
    }
 
    if (buffer->cache_count < buffer_space) {
        /* Add payloads to the cache, if able */
        while (buffer->cache_count < CACHED_PAYLOAD_MAX && buffer->cache_count < buffer_space) {
            struct data_buffer_payload_entry *buffer_payload;
 
            buffer_payload = data_buffer_payload_alloc(NULL, -1);
            if (buffer_payload) {
                AST_LIST_INSERT_TAIL(&buffer->cached_payloads, buffer_payload, list);
                buffer->cache_count++;
                continue;
            }
 
            ast_log(LOG_ERROR, "Failed to allocate memory to the cache.");
            break;
        }
    } else if (buffer->cache_count > buffer_space) {
        /* Remove payloads from the cache */
        while (buffer->cache_count > buffer_space) {
            struct data_buffer_payload_entry *buffer_payload;
 
            buffer_payload = AST_LIST_REMOVE_HEAD(&buffer->cached_payloads, list);
            if (buffer_payload) {
                ast_free(buffer_payload);
                buffer->cache_count--;
                continue;
            }
 
            ast_log(LOG_ERROR, "Failed to remove memory from the cache.");
            break;
        }
    }
}

References ast_assert, ast_free, AST_LIST_INSERT_TAIL, AST_LIST_REMOVE_HEAD, ast_log, ast_data_buffer::cache_count, CACHED_PAYLOAD_MAX, ast_data_buffer::cached_payloads, ast_data_buffer::count, data_buffer_payload_alloc(), data_buffer_payload_entry::list, LOG_ERROR, ast_data_buffer::max, and NULL.

Referenced by ast_data_buffer_alloc(), ast_data_buffer_put(), and ast_data_buffer_resize().

ast_data_buffer_count()

size_t ast_data_buffer_count

(

const struct ast_data_buffer *

buffer

)

Return the number of payloads in a data buffer.

Parameters

buffer

The data buffer

Returns

the number of data payloads

Since

15.4.0

Definition at line 356 of file data_buffer.c.

{
    ast_assert(buffer != NULL);
 
    return buffer->count;
}

References ast_assert, ast_data_buffer::count, and NULL.

Referenced by ast_rtp_read(), and AST_TEST_DEFINE().

ast_data_buffer_free()

void ast_data_buffer_free

(

struct ast_data_buffer *

buffer

)

Free a data buffer (and all held data payloads)

Parameters

buffer

The data buffer

Since

15.4.0

Definition at line 338 of file data_buffer.c.

{
    struct data_buffer_payload_entry *buffer_payload;
 
    ast_assert(buffer != NULL);
 
    while ((buffer_payload = AST_LIST_REMOVE_HEAD(&buffer->payloads, list))) {
        buffer->free_fn(buffer_payload->payload);
        ast_free(buffer_payload);
    }
 
    while ((buffer_payload = AST_LIST_REMOVE_HEAD(&buffer->cached_payloads, list))) {
        ast_free(buffer_payload);
    }
 
    ast_free(buffer);
}

References ast_assert, ast_free, AST_LIST_REMOVE_HEAD, ast_data_buffer::cached_payloads, ast_data_buffer::free_fn, data_buffer_payload_entry::list, NULL, data_buffer_payload_entry::payload, and ast_data_buffer::payloads.

Referenced by ast_data_buffer_free_wrapper(), ast_rtp_destroy(), and ast_rtp_prop_set().

ast_data_buffer_get()

void * ast_data_buffer_get	(	const struct ast_data_buffer *	buffer,
		size_t	pos
	)

Retrieve a data payload from the data buffer.

Parameters

buffer	The data buffer
pos	The position of the data payload

Return values

non-NULL	success
NULL	failure

Note

This does not remove the data payload from the data buffer. It will be removed when it is displaced.

Since

15.4.0

Definition at line 269 of file data_buffer.c.

{
    struct data_buffer_payload_entry *buffer_payload;
 
    ast_assert(buffer != NULL);
 
    AST_LIST_TRAVERSE(&buffer->payloads, buffer_payload, list) {
        if (buffer_payload->pos == pos) {
            return buffer_payload->payload;
        }
    }
 
    return NULL;
}

References ast_assert, AST_LIST_TRAVERSE, data_buffer_payload_entry::list, NULL, data_buffer_payload_entry::payload, ast_data_buffer::payloads, and data_buffer_payload_entry::pos.

Referenced by ast_rtp_read(), ast_rtp_rtcp_handle_nack(), and AST_TEST_DEFINE().

ast_data_buffer_max()

size_t ast_data_buffer_max

(

const struct ast_data_buffer *

buffer

)

Return the maximum number of payloads a data buffer can hold.

Parameters

buffer

The data buffer

Returns

the maximum number of data payloads

Since

15.4.0

Definition at line 363 of file data_buffer.c.

{
    ast_assert(buffer != NULL);
 
    return buffer->max;
}

References ast_assert, ast_data_buffer::max, and NULL.

Referenced by ast_rtp_read(), ast_rtp_rtcp_handle_nack(), and AST_TEST_DEFINE().

ast_data_buffer_put()

int ast_data_buffer_put	(	struct ast_data_buffer *	buffer,
		size_t	pos,
		void *	payload
	)

Place a data payload at a position in the data buffer.

Parameters

buffer	The data buffer
pos	The position of the data payload
payload	The data payload

Return values

0	success
-1	failure

Note

It is up to the consumer of this API to ensure proper memory management of data payloads

Since

15.4.0

Definition at line 203 of file data_buffer.c.

{
    struct data_buffer_payload_entry *buffer_payload = NULL;
    struct data_buffer_payload_entry *existing_payload;
    int inserted = 0;
 
    ast_assert(buffer != NULL);
    ast_assert(payload != NULL);
 
    /* If the data buffer has reached its maximum size then the head goes away and
     * we will reuse its buffer payload
     */
    if (buffer->count == buffer->max) {
        buffer_payload = AST_LIST_REMOVE_HEAD(&buffer->payloads, list);
        buffer->free_fn(buffer_payload->payload);
        buffer->count--;
 
        /* Update this buffer payload with its new information */
        buffer_payload->payload = payload;
        buffer_payload->pos = pos;
    }
    if (!buffer_payload) {
        if (!buffer->cache_count) {
            ast_data_buffer_cache_adjust(buffer);
        }
        buffer_payload = AST_LIST_REMOVE_HEAD(&buffer->cached_payloads, list);
        buffer->cache_count--;
 
        /* Update the payload from the cache with its new information */
        buffer_payload->payload = payload;
        buffer_payload->pos = pos;
    }
    if (!buffer_payload) {
        return -1;
    }
 
    /* Given the position find its ideal spot within the buffer */
    AST_LIST_TRAVERSE_SAFE_BEGIN(&buffer->payloads, existing_payload, list) {
        /* If it's already in the buffer, drop it */
        if (existing_payload->pos == pos) {
            ast_debug(3, "Packet with position %zu is already in buffer. Not inserting.\n", pos);
            inserted = -1;
            break;
        }
 
        if (existing_payload->pos > pos) {
            AST_LIST_INSERT_BEFORE_CURRENT(buffer_payload, list);
            inserted = 1;
            break;
        }
    }
    AST_LIST_TRAVERSE_SAFE_END;
 
    if (inserted == -1) {
        return -1;
    }
 
    if (!inserted) {
        AST_LIST_INSERT_TAIL(&buffer->payloads, buffer_payload, list);
    }
 
    buffer->count++;
 
    return 0;
}

References ast_assert, ast_data_buffer_cache_adjust(), ast_debug, AST_LIST_INSERT_BEFORE_CURRENT, AST_LIST_INSERT_TAIL, AST_LIST_REMOVE_HEAD, AST_LIST_TRAVERSE_SAFE_BEGIN, AST_LIST_TRAVERSE_SAFE_END, ast_data_buffer::cache_count, ast_data_buffer::cached_payloads, ast_data_buffer::count, ast_data_buffer::free_fn, data_buffer_payload_entry::list, ast_data_buffer::max, NULL, data_buffer_payload_entry::payload, ast_data_buffer::payloads, and data_buffer_payload_entry::pos.

Referenced by ast_rtp_read(), AST_TEST_DEFINE(), and rtp_raw_write().

ast_data_buffer_remove()

void * ast_data_buffer_remove	(	struct ast_data_buffer *	buffer,
		size_t	pos
	)

Remove a data payload from the data buffer.

Parameters

buffer	The data buffer
pos	The position of the data payload

Return values

non-NULL	success
NULL	failure

Note

This DOES remove the data payload from the data buffer. It does not free it, though.

Since

15.5.0

Definition at line 299 of file data_buffer.c.

{
    struct data_buffer_payload_entry *buffer_payload;
 
    ast_assert(buffer != NULL);
 
    AST_LIST_TRAVERSE_SAFE_BEGIN(&buffer->payloads, buffer_payload, list) {
        if (buffer_payload->pos == pos) {
            void *payload = buffer_payload->payload;
 
            AST_LIST_REMOVE_CURRENT(list);
            data_buffer_free_buffer_payload(buffer, buffer_payload);
 
            return payload;
        }
    }
    AST_LIST_TRAVERSE_SAFE_END;
 
    return NULL;
}

References ast_assert, AST_LIST_REMOVE_CURRENT, AST_LIST_TRAVERSE_SAFE_BEGIN, AST_LIST_TRAVERSE_SAFE_END, data_buffer_free_buffer_payload(), data_buffer_payload_entry::list, NULL, data_buffer_payload_entry::payload, ast_data_buffer::payloads, and data_buffer_payload_entry::pos.

Referenced by ast_rtp_read(), and AST_TEST_DEFINE().

ast_data_buffer_remove_head()

void * ast_data_buffer_remove_head

(

struct ast_data_buffer *

buffer

)

Remove the first payload from the data buffer.

Parameters

buffer

The data buffer

Return values

non-NULL	success
NULL	failure

Note

This DOES remove the data payload from the data buffer.

Since

15.5.0

Definition at line 320 of file data_buffer.c.

{
    ast_assert(buffer != NULL);
 
    if (buffer->count > 0) {
        struct data_buffer_payload_entry *buffer_payload;
        void *payload;
 
        buffer_payload = AST_LIST_REMOVE_HEAD(&buffer->payloads, list);
        payload = buffer_payload->payload;
        data_buffer_free_buffer_payload(buffer, buffer_payload);
 
        return payload;
    }
 
    return NULL;
}

References ast_assert, AST_LIST_REMOVE_HEAD, ast_data_buffer::count, data_buffer_free_buffer_payload(), data_buffer_payload_entry::list, NULL, data_buffer_payload_entry::payload, and ast_data_buffer::payloads.

Referenced by AST_TEST_DEFINE().

ast_data_buffer_resize()

void ast_data_buffer_resize	(	struct ast_data_buffer *	buffer,
		size_t	size
	)

Resize a data buffer.

Parameters

buffer	The data buffer
size	The new maximum size of the data buffer

Note

If the data buffer is shrunk any old data payloads will be freed using the configured callback. The data buffer is flexible and can be used for multiple purposes. Therefore it is up to the caller of the function to know whether or not a buffer should have its size changed. Increasing the size of the buffer may make sense in some scenarios, but shrinking should always be handled with caution since data can be lost.

Since

15.4.0

Definition at line 168 of file data_buffer.c.

{
    struct data_buffer_payload_entry *existing_payload;
 
    ast_assert(buffer != NULL);
 
    /* The buffer must have at least a size of 1 */
    ast_assert(size > 0);
 
    if (buffer->max == size) {
        return;
    }
 
    /* If the size is decreasing, some payloads will need to be freed */
    if (buffer->max > size) {
        int remove = buffer->max - size;
 
        AST_LIST_TRAVERSE_SAFE_BEGIN(&buffer->payloads, existing_payload, list) {
            if (remove) {
                AST_LIST_REMOVE_HEAD(&buffer->payloads, list);
                buffer->free_fn(existing_payload->payload);
                ast_free(existing_payload);
                buffer->count--;
                remove--;
                continue;
            }
            break;
        }
        AST_LIST_TRAVERSE_SAFE_END;
    }
 
    buffer->max = size;
    ast_data_buffer_cache_adjust(buffer);
}

References ast_assert, ast_data_buffer_cache_adjust(), ast_free, AST_LIST_REMOVE_HEAD, AST_LIST_TRAVERSE_SAFE_BEGIN, AST_LIST_TRAVERSE_SAFE_END, ast_data_buffer::count, ast_data_buffer::free_fn, data_buffer_payload_entry::list, ast_data_buffer::max, NULL, data_buffer_payload_entry::payload, ast_data_buffer::payloads, and remove.

Referenced by ast_rtp_read(), ast_rtp_rtcp_handle_nack(), and AST_TEST_DEFINE().

data_buffer_free_buffer_payload()

static void data_buffer_free_buffer_payload ( struct ast_data_buffer *  buffer, struct data_buffer_payload_entry *  buffer_payload  )

static

Definition at line 284 of file data_buffer.c.

{
    buffer_payload->payload = NULL;
    buffer->count--;
 
    if (buffer->cache_count < CACHED_PAYLOAD_MAX
            && buffer->cache_count < (buffer->max - buffer->count)) {
        AST_LIST_INSERT_TAIL(&buffer->cached_payloads, buffer_payload, list);
        buffer->cache_count++;
    } else {
        ast_free(buffer_payload);
    }
}

References ast_free, AST_LIST_INSERT_TAIL, ast_data_buffer::cache_count, CACHED_PAYLOAD_MAX, ast_data_buffer::cached_payloads, ast_data_buffer::count, data_buffer_payload_entry::list, ast_data_buffer::max, NULL, and data_buffer_payload_entry::payload.

Referenced by ast_data_buffer_remove(), and ast_data_buffer_remove_head().

data_buffer_payload_alloc()

static struct data_buffer_payload_entry * data_buffer_payload_alloc ( void *  payload, size_t  pos  )

static

Helper function to allocate a data payload.

Definition at line 82 of file data_buffer.c.

{
    struct data_buffer_payload_entry *data_payload;
 
    data_payload = ast_calloc(1, sizeof(*data_payload));
    if (!data_payload) {
        return NULL;
    }
 
    data_payload->payload = payload;
    data_payload->pos = pos;
 
    return data_payload;
}

References ast_calloc, NULL, data_buffer_payload_entry::payload, and data_buffer_payload_entry::pos.

Referenced by ast_data_buffer_cache_adjust().

free_fn_do_nothing()

static void free_fn_do_nothing ( void *  data )

static

Definition at line 74 of file data_buffer.c.

{
    return;
}

Referenced by ast_data_buffer_alloc().