src/pulsecore/memblockq.h

   1 #ifndef foomemblockqhfoo
   2 #define foomemblockqhfoo
   3
   4 /***
   5   This file is part of PulseAudio.
   6
   7   Copyright 2004-2006 Lennart Poettering
   8
   9   PulseAudio is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU Lesser General Public License as
  11   published by the Free Software Foundation; either version 2.1 of the
  12   License, or (at your option) any later version.
  13
  14   PulseAudio is distributed in the hope that it will be useful, but
  15   WITHOUT ANY WARRANTY; without even the implied warranty of
  16   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  17   General Public License for more details.
  18
  19   You should have received a copy of the GNU Lesser General Public
  20   License along with PulseAudio; if not, write to the Free Software
  21   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  22   USA.
  23 ***/
  24
  25 #include <sys/types.h>
  26 #include <inttypes.h>
  27
  28 #include <pulsecore/memblock.h>
  29 #include <pulsecore/memchunk.h>
  30 #include <pulse/def.h>
  31
  32 /* A memblockq is a queue of pa_memchunks (yepp, the name is not
  33  * perfect). It is similar to the ring buffers used by most other
  34  * audio software. In contrast to a ring buffer this memblockq data
  35  * type doesn't need to copy any data around, it just maintains
  36  * references to reference counted memory blocks. */
  37
  38 typedef struct pa_memblockq pa_memblockq;
  39
  40
  41 /* Parameters:
  42
  43    - idx:       start value for both read and write index
  44
  45    - maxlength: maximum length of queue. If more data is pushed into
  46                 the queue, the operation will fail. Must not be 0.
  47
  48    - tlength:   the target length of the queue. Pass 0 for the default.
  49
  50    - base:      a base value for all metrics. Only multiples of this value
  51                 are popped from the queue or should be pushed into
  52                 it. Must not be 0.
  53
  54    - prebuf:    If the queue runs empty wait until this many bytes are in
  55                 queue again before passing the first byte out. If set
  56                 to 0 pa_memblockq_pop() will return a silence memblock
  57                 if no data is in the queue and will never fail. Pass
  58                 (size_t) -1 for the default.
  59
  60    - minreq:    pa_memblockq_missing() will only return values greater
  61                 than this value. Pass 0 for the default.
  62
  63    - maxrewind: how many bytes of history to keep in the queue
  64
  65    - silence:   return this memchunk when reading unitialized data
  66 */
  67 pa_memblockq* pa_memblockq_new(
  68         int64_t idx,
  69         size_t maxlength,
  70         size_t tlength,
  71         size_t base,
  72         size_t prebuf,
  73         size_t minreq,
  74         size_t maxrewind,
  75         pa_memchunk *silence);
  76
  77 void pa_memblockq_free(pa_memblockq*bq);
  78
  79 /* Push a new memory chunk into the queue.  */
  80 int pa_memblockq_push(pa_memblockq* bq, const pa_memchunk *chunk);
  81
  82 /* Push a new memory chunk into the queue, but filter it through a
  83  * pa_mcalign object. Don't mix this with pa_memblockq_seek() unless
  84  * you know what you do. */
  85 int pa_memblockq_push_align(pa_memblockq* bq, const pa_memchunk *chunk);
  86
  87 /* Manipulate the write pointer */
  88 void pa_memblockq_seek(pa_memblockq *bq, int64_t offset, pa_seek_mode_t seek, pa_bool_t account);
  89
  90 /* Return a copy of the next memory chunk in the queue. It is not
  91  * removed from the queue. There are two reasons this function might
  92  * fail: 1. prebuffering is active, 2. queue is empty and no silence
  93  * memblock was passed at initialization. If the queue is not empty,
  94  * but we're currently at a hole in the queue and no silence memblock
  95  * was passed we return the length of the hole in chunk->length. */
  96 int pa_memblockq_peek(pa_memblockq* bq, pa_memchunk *chunk);
  97
  98 /* Drop the specified bytes from the queue. */
  99 void pa_memblockq_drop(pa_memblockq *bq, size_t length);
 100
 101 /* Rewind the read index. If the history is shorter than the specified length we'll point to silence afterwards. */
 102 void pa_memblockq_rewind(pa_memblockq *bq, size_t length);
 103
 104 /* Test if the pa_memblockq is currently readable, that is, more data than base */
 105 pa_bool_t pa_memblockq_is_readable(pa_memblockq *bq);
 106
 107 /* Return the length of the queue in bytes */
 108 size_t pa_memblockq_get_length(pa_memblockq *bq);
 109
 110 /* Return how many bytes are missing in queue to the specified fill amount */
 111 size_t pa_memblockq_missing(pa_memblockq *bq);
 112
 113 /* Return the number of bytes that are missing since the last call to
 114  * this function, reset the internal counter to 0. */
 115 size_t pa_memblockq_pop_missing(pa_memblockq *bq);
 116
 117 /* Directly moves the data from the source memblockq into bq */
 118 int pa_memblockq_splice(pa_memblockq *bq, pa_memblockq *source);
 119
 120 /* Set the queue to silence, set write index to read index */
 121 void pa_memblockq_flush_write(pa_memblockq *bq);
 122
 123 /* Set the queue to silence, set write read index to write index*/
 124 void pa_memblockq_flush_read(pa_memblockq *bq);
 125
 126 /* Ignore prebuf for now */
 127 void pa_memblockq_prebuf_disable(pa_memblockq *bq);
 128
 129 /* Force prebuf */
 130 void pa_memblockq_prebuf_force(pa_memblockq *bq);
 131
 132 /* Return the maximum length of the queue in bytes */
 133 size_t pa_memblockq_get_maxlength(pa_memblockq *bq);
 134
 135 /* Get Target length */
 136 size_t pa_memblockq_get_tlength(pa_memblockq *bq);
 137
 138 /* Return the prebuffer length in bytes */
 139 size_t pa_memblockq_get_prebuf(pa_memblockq *bq);
 140
 141 /* Returns the minimal request value */
 142 size_t pa_memblockq_get_minreq(pa_memblockq *bq);
 143
 144 /* Returns the maximal rewind value */
 145 size_t pa_memblockq_get_maxrewind(pa_memblockq *bq);
 146
 147 /* Return the base unit in bytes */
 148 size_t pa_memblockq_get_base(pa_memblockq *bq);
 149
 150 /* Return the current read index */
 151 int64_t pa_memblockq_get_read_index(pa_memblockq *bq);
 152
 153 /* Return the current write index */
 154 int64_t pa_memblockq_get_write_index(pa_memblockq *bq);
 155
 156 /* Change metrics. Always call in order. */
 157 void pa_memblockq_set_maxlength(pa_memblockq *memblockq, size_t maxlength); /* might modify tlength, prebuf, minreq too */
 158 void pa_memblockq_set_tlength(pa_memblockq *memblockq, size_t tlength); /* might modify minreq, too */
 159 void pa_memblockq_set_prebuf(pa_memblockq *memblockq, size_t prebuf); /* might modify minreq, too */
 160 void pa_memblockq_set_minreq(pa_memblockq *memblockq, size_t minreq);
 161 void pa_memblockq_set_maxrewind(pa_memblockq *memblockq, size_t maxrewind); /* Set the maximum history size */
 162 void pa_memblockq_set_silence(pa_memblockq *memblockq, pa_memchunk *silence);
 163
 164 /* Apply the data from pa_buffer_attr */
 165 void pa_memblockq_apply_attr(pa_memblockq *memblockq, const pa_buffer_attr *a);
 166 void pa_memblockq_get_attr(pa_memblockq *bq, pa_buffer_attr *a);
 167
 168 /* Call pa_memchunk_willneed() for every chunk in the queue from the current read pointer to the end */
 169 void pa_memblockq_willneed(pa_memblockq *bq);
 170
 171 /* Check whether the memblockq is completely empty, i.e. no data
 172  * neither left nor right of the read pointer, and hence no buffered
 173  * data for the future nor data in the backlog. */
 174 pa_bool_t pa_memblockq_is_empty(pa_memblockq *bq);
 175
 176 /* Drop everything in the queue, but don't modify the indexes */
 177 void pa_memblockq_silence(pa_memblockq *bq);
 178
 179 /* Check whether we currently are in prebuf state */
 180 pa_bool_t pa_memblockq_prebuf_active(pa_memblockq *bq);
 181
 182 /* Return how many items are currently stored in the queue */
 183 unsigned pa_memblockq_get_nblocks(pa_memblockq *bq);
 184
 185 #endif