spandsp: queue.h Source File

spandsp 0.0.6

queue.h
Go to the documentation of this file.
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
26/*! \file */
27
28/*! \page queue_page Queuing
29\section queue_page_sec_1 What does it do?
30This module provides lock free queuing for either octet streams or messages.
31Specifically, lock free means one thread can write and another can read without
32locking the queue. It does NOT means a free-for-all is possible, with many
33threads writing or many threads reading. Those things would require locking,
34to avoid conflicts between the multiple threads acting on one end of the queue.
35
36\section queue_page_sec_2 How does it work?
37???.
38*/
39
40#if !defined(_SPANDSP_QUEUE_H_)
41#define _SPANDSP_QUEUE_H_
42
43/*! Flag bit to indicate queue reads are atomic operations. This must be set
44 if the queue is to be used with the message oriented functions. */
45#define QUEUE_READ_ATOMIC 0x0001
46/*! Flag bit to indicate queue writes are atomic operations. This must be set
47 if the queue is to be used with the message oriented functions. */
48#define QUEUE_WRITE_ATOMIC 0x0002
49
50/*!
51 Queue descriptor. This defines the working state for a single instance of
52 a byte stream or message oriented queue.
53*/
54 typedef struct queue_state_s queue_state_t;
55
56#define QUEUE_STATE_T_SIZE(len) (sizeof(queue_state_t) + len + 1)
57
58#if defined(__cplusplus)
59extern "C"
60{
61#endif
62
63/*! Check if a queue is empty.
64 \brief Check if a queue is empty.
65 \param s The queue context.
66 \return TRUE if empty, else FALSE. */
67SPAN_DECLARE(int) queue_empty(queue_state_t *s);
68
69/*! Check the available free space in a queue's buffer.
70 \brief Check available free space.
71 \param s The queue context.
72 \return The number of bytes of free space. */
73SPAN_DECLARE(int) queue_free_space(queue_state_t *s);
74
75/*! Check the contents of a queue.
76 \brief Check the contents of a queue.
77 \param s The queue context.
78 \return The number of bytes in the queue. */
79SPAN_DECLARE(int) queue_contents(queue_state_t *s);
80
81/*! Flush the contents of a queue.
82 \brief Flush the contents of a queue.
83 \param s The queue context. */
84SPAN_DECLARE(void) queue_flush(queue_state_t *s);
85
86/*! Copy bytes from a queue. This is similar to queue_read, but
87 the data remains in the queue.
88 \brief Copy bytes from a queue.
89 \param s The queue context.
90 \param buf The buffer into which the bytes will be read.
91 \param len The length of the buffer.
92 \return the number of bytes returned. */
93SPAN_DECLARE(int) queue_view(queue_state_t *s, uint8_t *buf, int len);
94
95/*! Read bytes from a queue.
96 \brief Read bytes from a queue.
97 \param s The queue context.
98 \param buf The buffer into which the bytes will be read.
99 \param len The length of the buffer.
100 \return the number of bytes returned. */
101SPAN_DECLARE(int) queue_read(queue_state_t *s, uint8_t *buf, int len);
102
103/*! Read a byte from a queue.
104 \brief Read a byte from a queue.
105 \param s The queue context.
106 \return the byte, or -1 if the queue is empty. */
107SPAN_DECLARE(int) queue_read_byte(queue_state_t *s);
108
109/*! Write bytes to a queue.
110 \brief Write bytes to a queue.
111 \param s The queue context.
112 \param buf The buffer containing the bytes to be written.
113 \param len The length of the buffer.
114 \return the number of bytes actually written. */
115SPAN_DECLARE(int) queue_write(queue_state_t *s, const uint8_t *buf, int len);
116
117/*! Write a byte to a queue.
118 \brief Write a byte to a queue.
119 \param s The queue context.
120 \param byte The byte to be written.
121 \return the number of bytes actually written. */
122SPAN_DECLARE(int) queue_write_byte(queue_state_t *s, uint8_t byte);
123
124/*! Test the length of the message at the head of a queue.
125 \brief Test message length.
126 \param s The queue context.
127 \return The length of the next message, in byte. If there are
128 no messages in the queue, -1 is returned. */
129SPAN_DECLARE(int) queue_state_test_msg(queue_state_t *s);
130
131/*! Read a message from a queue. If the message is longer than the buffer
132 provided, only the first len bytes of the message will be returned. The
133 remainder of the message will be discarded.
134 \brief Read a message from a queue.
135 \param s The queue context.
136 \param buf The buffer into which the message will be read.
137 \param len The length of the buffer.
138 \return The number of bytes returned. If there are
139 no messages in the queue, -1 is returned. */
140SPAN_DECLARE(int) queue_read_msg(queue_state_t *s, uint8_t *buf, int len);
141
142/*! Write a message to a queue.
143 \brief Write a message to a queue.
144 \param s The queue context.
145 \param buf The buffer from which the message will be written.
146 \param len The length of the message.
147 \return The number of bytes actually written. */
148SPAN_DECLARE(int) queue_write_msg(queue_state_t *s, const uint8_t *buf, int len);
149
150/*! Initialise a queue.
151 \brief Initialise a queue.
152 \param s The queue context. If is imperative that the context this
153 points to is immediately followed by a buffer of the required
154 size + 1 octet.
155 \param len The length of the queue's buffer.
156 \param flags Flags controlling the operation of the queue.
157 Valid flags are QUEUE_READ_ATOMIC and QUEUE_WRITE_ATOMIC.
158 \return A pointer to the context if OK, else NULL. */
159SPAN_DECLARE(queue_state_t *) queue_init(queue_state_t *s, int len, int flags);
160
161/*! Release a queue.
162 \brief Release a queue.
163 \param s The queue context.
164 \return 0 if OK, else -1. */
165SPAN_DECLARE(int) queue_release(queue_state_t *s);
166
167/*! Free a queue.
168 \brief Delete a queue.
169 \param s The queue context.
170 \return 0 if OK, else -1. */
171SPAN_DECLARE(int) queue_free(queue_state_t *s);
172
173#if defined(__cplusplus)
174}
175#endif
176
177#endif
178/*- End of file ------------------------------------------------------------*/
queue_read_msg
int queue_read_msg(queue_state_t *s, uint8_t *buf, int len)
Read a message from a queue.
Definition queue.c:309
queue_read
int queue_read(queue_state_t *s, uint8_t *buf, int len)
Read bytes from a queue.
Definition queue.c:130
queue_read_byte
int queue_read_byte(queue_state_t *s)
Read a byte from a queue.
Definition queue.c:188
queue_release
int queue_release(queue_state_t *s)
Release a queue.
Definition queue.c:409
queue_write
int queue_write(queue_state_t *s, const uint8_t *buf, int len)
Write bytes to a queue.
Definition queue.c:214
queue_empty
int queue_empty(queue_state_t *s)
Check if a queue is empty.
Definition queue.c:46
queue_state_test_msg
int queue_state_test_msg(queue_state_t *s)
Test message length.
Definition queue.c:298
queue_view
int queue_view(queue_state_t *s, uint8_t *buf, int len)
Copy bytes from a queue.
Definition queue.c:80
queue_flush
void queue_flush(queue_state_t *s)
Flush the contents of a queue.
Definition queue.c:74
queue_contents
int queue_contents(queue_state_t *s)
Check the contents of a queue.
Definition queue.c:63
queue_free_space
int queue_free_space(queue_state_t *s)
Check available free space.
Definition queue.c:52
queue_free
int queue_free(queue_state_t *s)
Delete a queue.
Definition queue.c:415
queue_write_msg
int queue_write_msg(queue_state_t *s, const uint8_t *buf, int len)
Write a message to a queue.
Definition queue.c:335
queue_write_byte
int queue_write_byte(queue_state_t *s, uint8_t byte)
Write a byte to a queue.
Definition queue.c:267
queue_init
queue_state_t * queue_init(queue_state_t *s, int len, int flags)
Initialise a queue.
Definition queue.c:394
queue_state_s
Definition private/queue.h:34
queue_state_s::flags
int flags
Flags indicating the mode of the queue.
Definition private/queue.h:36
queue_state_s::len
int len
The length of the data buffer.
Definition private/queue.h:38