data_buffer.h File Reference

Data Buffer API. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef void(*	ast_data_buffer_free_callback) (void *data)
	A callback function to free a data payload in a data buffer. 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...
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...

Detailed Description

Data Buffer API.

A data buffer acts as a ring buffer of data. It is given a fixed number of data packets to store (which may be dynamically changed). Given a number it will store a data packet at that position relative to the others. Given a number it will retrieve the given data packet if it is present. This is purposely a storage of arbitrary things so that it can be used for multiple things.

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.h.

Typedef Documentation

ast_data_buffer_free_callback

typedef void(* ast_data_buffer_free_callback) (void *data)

A callback function to free a data payload in a data buffer.

Parameters

The	data payload

Definition at line 48 of file data_buffer.h.

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.

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().

{
   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;
}

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

Return values

the	number of data payloads

Since

15.4.0

Definition at line 356 of file data_buffer.c.

References ast_assert, ast_data_buffer::count, and NULL.

Referenced by ast_rtp_read(), AST_TEST_DEFINE(), get_recv_buffer_count(), and get_send_buffer_count().

{
   ast_assert(buffer != NULL);

   return buffer->count;
}

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.

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().

{
   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);
}

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.

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().

{
   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;
}

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

Return values

the	maximum number of data payloads

Since

15.4.0

Definition at line 363 of file data_buffer.c.

References ast_assert, ast_data_buffer::max, and NULL.

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

{
   ast_assert(buffer != NULL);

   return buffer->max;
}

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.

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().

{
   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;
}

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.

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().

{
   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;
}

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.

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_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;
}

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.

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, and ast_data_buffer::payloads.

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

{
   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);
}