Mercurial > hg > audiostuff
comparison spandsp-0.0.6pre17/src/spandsp/queue.h @ 4:26cd8f1ef0b1
import spandsp-0.0.6pre17
author | Peter Meerwald <pmeerw@cosy.sbg.ac.at> |
---|---|
date | Fri, 25 Jun 2010 15:50:58 +0200 |
parents | |
children |
comparison
equal
deleted
inserted
replaced
3:c6c5a16ce2f2 | 4:26cd8f1ef0b1 |
---|---|
1 /* | |
2 * SpanDSP - a series of DSP components for telephony | |
3 * | |
4 * queue.h - simple in process message queuing | |
5 * | |
6 * Written by Steve Underwood <steveu@coppice.org> | |
7 * | |
8 * Copyright (C) 2004 Steve Underwood | |
9 * | |
10 * All rights reserved. | |
11 * | |
12 * This program is free software; you can redistribute it and/or modify | |
13 * it under the terms of the GNU Lesser General Public License version 2.1, | |
14 * as published by the Free Software Foundation. | |
15 * | |
16 * This program is distributed in the hope that it will be useful, | |
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
19 * GNU Lesser General Public License for more details. | |
20 * | |
21 * You should have received a copy of the GNU Lesser General Public | |
22 * License along with this program; if not, write to the Free Software | |
23 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. | |
24 * | |
25 * $Id: queue.h,v 1.21 2009/02/10 13:06:47 steveu Exp $ | |
26 */ | |
27 | |
28 /*! \file */ | |
29 | |
30 /*! \page queue_page Queuing | |
31 \section queue_page_sec_1 What does it do? | |
32 This module provides lock free queuing for either octet streams or messages. | |
33 Specifically, lock free means one thread can write and another can read without | |
34 locking the queue. It does NOT means a free-for-all is possible, with many | |
35 threads writing or many threads reading. Those things would require locking, | |
36 to avoid conflicts between the multiple threads acting on one end of the queue. | |
37 | |
38 \section queue_page_sec_2 How does it work? | |
39 ???. | |
40 */ | |
41 | |
42 #if !defined(_SPANDSP_QUEUE_H_) | |
43 #define _SPANDSP_QUEUE_H_ | |
44 | |
45 /*! Flag bit to indicate queue reads are atomic operations. This must be set | |
46 if the queue is to be used with the message oriented functions. */ | |
47 #define QUEUE_READ_ATOMIC 0x0001 | |
48 /*! Flag bit to indicate queue writes are atomic operations. This must be set | |
49 if the queue is to be used with the message oriented functions. */ | |
50 #define QUEUE_WRITE_ATOMIC 0x0002 | |
51 | |
52 /*! | |
53 Queue descriptor. This defines the working state for a single instance of | |
54 a byte stream or message oriented queue. | |
55 */ | |
56 typedef struct queue_state_s queue_state_t; | |
57 | |
58 #define QUEUE_STATE_T_SIZE(len) (sizeof(queue_state_t) + len + 1) | |
59 | |
60 #if defined(__cplusplus) | |
61 extern "C" | |
62 { | |
63 #endif | |
64 | |
65 /*! Check if a queue is empty. | |
66 \brief Check if a queue is empty. | |
67 \param s The queue context. | |
68 \return TRUE if empty, else FALSE. */ | |
69 SPAN_DECLARE(int) queue_empty(queue_state_t *s); | |
70 | |
71 /*! Check the available free space in a queue's buffer. | |
72 \brief Check available free space. | |
73 \param s The queue context. | |
74 \return The number of bytes of free space. */ | |
75 SPAN_DECLARE(int) queue_free_space(queue_state_t *s); | |
76 | |
77 /*! Check the contents of a queue. | |
78 \brief Check the contents of a queue. | |
79 \param s The queue context. | |
80 \return The number of bytes in the queue. */ | |
81 SPAN_DECLARE(int) queue_contents(queue_state_t *s); | |
82 | |
83 /*! Flush the contents of a queue. | |
84 \brief Flush the contents of a queue. | |
85 \param s The queue context. */ | |
86 SPAN_DECLARE(void) queue_flush(queue_state_t *s); | |
87 | |
88 /*! Copy bytes from a queue. This is similar to queue_read, but | |
89 the data remains in the queue. | |
90 \brief Copy bytes from a queue. | |
91 \param s The queue context. | |
92 \param buf The buffer into which the bytes will be read. | |
93 \param len The length of the buffer. | |
94 \return the number of bytes returned. */ | |
95 SPAN_DECLARE(int) queue_view(queue_state_t *s, uint8_t *buf, int len); | |
96 | |
97 /*! Read bytes from a queue. | |
98 \brief Read bytes from a queue. | |
99 \param s The queue context. | |
100 \param buf The buffer into which the bytes will be read. | |
101 \param len The length of the buffer. | |
102 \return the number of bytes returned. */ | |
103 SPAN_DECLARE(int) queue_read(queue_state_t *s, uint8_t *buf, int len); | |
104 | |
105 /*! Read a byte from a queue. | |
106 \brief Read a byte from a queue. | |
107 \param s The queue context. | |
108 \return the byte, or -1 if the queue is empty. */ | |
109 SPAN_DECLARE(int) queue_read_byte(queue_state_t *s); | |
110 | |
111 /*! Write bytes to a queue. | |
112 \brief Write bytes to a queue. | |
113 \param s The queue context. | |
114 \param buf The buffer containing the bytes to be written. | |
115 \param len The length of the buffer. | |
116 \return the number of bytes actually written. */ | |
117 SPAN_DECLARE(int) queue_write(queue_state_t *s, const uint8_t *buf, int len); | |
118 | |
119 /*! Write a byte to a queue. | |
120 \brief Write a byte to a queue. | |
121 \param s The queue context. | |
122 \param byte The byte to be written. | |
123 \return the number of bytes actually written. */ | |
124 SPAN_DECLARE(int) queue_write_byte(queue_state_t *s, uint8_t byte); | |
125 | |
126 /*! Test the length of the message at the head of a queue. | |
127 \brief Test message length. | |
128 \param s The queue context. | |
129 \return The length of the next message, in byte. If there are | |
130 no messages in the queue, -1 is returned. */ | |
131 SPAN_DECLARE(int) queue_state_test_msg(queue_state_t *s); | |
132 | |
133 /*! Read a message from a queue. If the message is longer than the buffer | |
134 provided, only the first len bytes of the message will be returned. The | |
135 remainder of the message will be discarded. | |
136 \brief Read a message from a queue. | |
137 \param s The queue context. | |
138 \param buf The buffer into which the message will be read. | |
139 \param len The length of the buffer. | |
140 \return The number of bytes returned. If there are | |
141 no messages in the queue, -1 is returned. */ | |
142 SPAN_DECLARE(int) queue_read_msg(queue_state_t *s, uint8_t *buf, int len); | |
143 | |
144 /*! Write a message to a queue. | |
145 \brief Write a message to a queue. | |
146 \param s The queue context. | |
147 \param buf The buffer from which the message will be written. | |
148 \param len The length of the message. | |
149 \return The number of bytes actually written. */ | |
150 SPAN_DECLARE(int) queue_write_msg(queue_state_t *s, const uint8_t *buf, int len); | |
151 | |
152 /*! Initialise a queue. | |
153 \brief Initialise a queue. | |
154 \param s The queue context. If is imperative that the context this | |
155 points to is immediately followed by a buffer of the required | |
156 size + 1 octet. | |
157 \param len The length of the queue's buffer. | |
158 \param flags Flags controlling the operation of the queue. | |
159 Valid flags are QUEUE_READ_ATOMIC and QUEUE_WRITE_ATOMIC. | |
160 \return A pointer to the context if OK, else NULL. */ | |
161 SPAN_DECLARE(queue_state_t *) queue_init(queue_state_t *s, int len, int flags); | |
162 | |
163 /*! Release a queue. | |
164 \brief Release a queue. | |
165 \param s The queue context. | |
166 \return 0 if OK, else -1. */ | |
167 SPAN_DECLARE(int) queue_release(queue_state_t *s); | |
168 | |
169 /*! Free a queue. | |
170 \brief Delete a queue. | |
171 \param s The queue context. | |
172 \return 0 if OK, else -1. */ | |
173 SPAN_DECLARE(int) queue_free(queue_state_t *s); | |
174 | |
175 #if defined(__cplusplus) | |
176 } | |
177 #endif | |
178 | |
179 #endif | |
180 /*- End of file ------------------------------------------------------------*/ |