1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
|
/*
* Copyright (C) 2003-2011 The Music Player Daemon Project
* http://www.musicpd.org
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* - Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* - Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the
* distribution.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
* ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
* FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
* FOUNDATION OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
* (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
* SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
* STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
* OF THE POSSIBILITY OF SUCH DAMAGE.
*/
/** \file
*
* This is a general purpose FIFO buffer library. You may append data
* at the end, while another instance reads data from the beginning.
* It is optimized for zero-copy usage: you get pointers to the real
* buffer, where you may operate on.
*
* This library is not thread safe.
*/
#ifndef MPD_FIFO_BUFFER_H
#define MPD_FIFO_BUFFER_H
#include <stdbool.h>
#include <stddef.h>
struct fifo_buffer;
/**
* Creates a new #fifo_buffer object. Free this object with
* fifo_buffer_free().
*
* @param size the size of the buffer in bytes
* @return the new #fifo_buffer object
*/
struct fifo_buffer *
fifo_buffer_new(size_t size);
/**
* Change the capacity of the #fifo_buffer, while preserving existing
* data.
*
* @param buffer the old buffer, may be NULL
* @param new_size the requested new size of the #fifo_buffer; must
* not be smaller than the data which is stored in the old buffer
* @return the new buffer, may be NULL if the requested new size is 0
*/
struct fifo_buffer *
fifo_buffer_realloc(struct fifo_buffer *buffer, size_t new_size);
/**
* Frees the resources consumed by this #fifo_buffer object.
*/
void
fifo_buffer_free(struct fifo_buffer *buffer);
/**
* Return the capacity of the buffer, i.e. the size that was passed to
* fifo_buffer_new().
*/
size_t
fifo_buffer_capacity(const struct fifo_buffer *buffer);
/**
* Return the number of bytes currently stored in the buffer.
*/
size_t
fifo_buffer_available(const struct fifo_buffer *buffer);
/**
* Clears all data currently in this #fifo_buffer object. This does
* not overwrite the actuall buffer; it just resets the internal
* pointers.
*/
void
fifo_buffer_clear(struct fifo_buffer *buffer);
/**
* Reads from the beginning of the buffer. To remove consumed data
* from the buffer, call fifo_buffer_consume().
*
* @param buffer the #fifo_buffer object
* @param length_r the maximum amount to read is returned here
* @return a pointer to the beginning of the buffer, or NULL if the
* buffer is empty
*/
const void *
fifo_buffer_read(const struct fifo_buffer *buffer, size_t *length_r);
/**
* Marks data at the beginning of the buffer as "consumed".
*
* @param buffer the #fifo_buffer object
* @param length the number of bytes which were consumed
*/
void
fifo_buffer_consume(struct fifo_buffer *buffer, size_t length);
/**
* Prepares writing to the buffer. This returns a buffer which you
* can write to. To commit the write operation, call
* fifo_buffer_append().
*
* @param buffer the #fifo_buffer object
* @param max_length_r the maximum amount to write is returned here
* @return a pointer to the end of the buffer, or NULL if the buffer
* is already full
*/
void *
fifo_buffer_write(struct fifo_buffer *buffer, size_t *max_length_r);
/**
* Commits the write operation initiated by fifo_buffer_write().
*
* @param buffer the #fifo_buffer object
* @param length the number of bytes which were written
*/
void
fifo_buffer_append(struct fifo_buffer *buffer, size_t length);
/**
* Checks if the buffer is empty.
*/
bool
fifo_buffer_is_empty(struct fifo_buffer *buffer);
/**
* Checks if the buffer is full.
*/
bool
fifo_buffer_is_full(struct fifo_buffer *buffer);
#endif
|
