queue.h

Go to the documentation of this file.
00001 /*
00002  * SpanDSP - a series of DSP components for telephony
00003  *
00004  * queue.h - simple in process message queuing
00005  *
00006  * Written by Steve Underwood <steveu@coppice.org>
00007  *
00008  * Copyright (C) 2004 Steve Underwood
00009  *
00010  * All rights reserved.
00011  *
00012  * This program is free software; you can redistribute it and/or modify
00013  * it under the terms of the GNU General Public License version 2, as
00014  * published by the Free Software Foundation.
00015  *
00016  * This program is distributed in the hope that it will be useful,
00017  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00018  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00019  * GNU General Public License for more details.
00020  *
00021  * You should have received a copy of the GNU General Public License
00022  * along with this program; if not, write to the Free Software
00023  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00024  *
00025  * $Id: queue.h,v 1.11 2007/05/19 18:34:42 steveu Exp $
00026  */
00027 
00028 /*! \file */
00029 
00030 /*! \page queue_page Queuing
00031 \section queue_page_sec_1 What does it do?
00032 This module provides lock free queuing for either octet streams or messages.
00033 Specifically, lock free means one thread can write and another can read without
00034 locking the queue. It does NOT means a free-for-all is possible, with many
00035 threads writing or many threads reading. Those things would require locking,
00036 to avoid conflicts between the multiple threads acting on one end of the queue.
00037 
00038 \section queue_page_sec_2 How does it work?
00039 ???.
00040 */
00041 
00042 #if !defined(_SPANDSP_QUEUE_H_)
00043 #define _SPANDSP_QUEUE_H_
00044 
00045 #define QUEUE_READ_ATOMIC   0x0001
00046 #define QUEUE_WRITE_ATOMIC  0x0002
00047 
00048 typedef struct
00049 {
00050     int flags;
00051     int len;
00052     volatile int iptr;
00053     volatile int optr;
00054     uint8_t data[];
00055 } queue_state_t;
00056 
00057 #if defined(__cplusplus)
00058 extern "C"
00059 {
00060 #endif
00061 
00062 /*! Check if a queue is empty.
00063     \brief Check if a queue is empty.
00064     \param s The queue context.
00065     \return TRUE if empty, else FALSE. */
00066 int queue_empty(queue_state_t *s);
00067 
00068 /*! Check the available free space in a queue's buffer.
00069     \brief Check available free space.
00070     \param s The queue context.
00071     \return The number of bytes of free space. */
00072 int queue_free_space(queue_state_t *s);
00073 
00074 /*! Check the contents of a queue.
00075     \brief Check the contents of a queue.
00076     \param s The queue context.
00077     \return The number of bytes in the queue. */
00078 int queue_contents(queue_state_t *s);
00079 
00080 /*! Flush the contents of a queue.
00081     \brief Flush the contents of a queue.
00082     \param s The queue context. */
00083 void queue_flush(queue_state_t *s);
00084 
00085 /*! Copy bytes from a queue. This is similar to queue_read, but
00086     the data remains in the queue.
00087     \brief Copy bytes from a queue.
00088     \param s The queue context.
00089     \param buf The buffer into which the bytes will be read.
00090     \param len The length of the buffer.
00091     \return the number of bytes returned. */
00092 int queue_view(queue_state_t *s, uint8_t *buf, int len);
00093 
00094 /*! Read bytes from a queue.
00095     \brief Read bytes from a queue.
00096     \param s The queue context.
00097     \param buf The buffer into which the bytes will be read.
00098     \param len The length of the buffer.
00099     \return the number of bytes returned. */
00100 int queue_read(queue_state_t *s, uint8_t *buf, int len);
00101 
00102 /*! Read a byte from a queue.
00103     \brief Read a byte from a queue.
00104     \param s The queue context.
00105     \return the byte, or -1 if the queue is empty. */
00106 int queue_read_byte(queue_state_t *s);
00107 
00108 /*! Write bytes to a queue.
00109     \brief Write bytes to a queue.
00110     \param s The queue context.
00111     \param buf The buffer containing the bytes to be written.
00112     \param len The length of the buffer.
00113     \return the number of bytes actually written. */
00114 int queue_write(queue_state_t *s, const uint8_t *buf, int len);
00115 
00116 /*! Write a byte to a queue.
00117     \brief Write a byte to a queue.
00118     \param s The queue context.
00119     \param byte The byte to be written.
00120     \return the number of bytes actually written. */
00121 int queue_write_byte(queue_state_t *s, uint8_t byte);
00122 
00123 /*! Test the length of the message at the head of a queue.
00124     \brief Test message length.
00125     \param s The queue context.
00126     \return The length of the next message, in byte. If there are
00127             no messages in the queue, -1 is returned. */
00128 int queue_state_test_msg(queue_state_t *s);
00129 
00130 /*! Read a message from a queue. If the message is longer than the buffer
00131     provided, only the first len bytes of the message will be returned. The
00132     remainder of the message will be discarded.
00133     \brief Read a message from a queue.
00134     \param s The queue context.
00135     \param buf The buffer into which the message will be read.
00136     \param len The length of the buffer.
00137     \return The number of bytes returned. If there are
00138             no messages in the queue, -1 is returned. */
00139 int queue_read_msg(queue_state_t *s, uint8_t *buf, int len);
00140 
00141 /*! Write a message to a queue.
00142     \brief Write a message to a queue.
00143     \param s The queue context.
00144     \param buf The buffer from which the message will be written.
00145     \param len The length of the message.
00146     \return The number of bytes actually written. */
00147 int queue_write_msg(queue_state_t *s, const uint8_t *buf, int len);
00148 
00149 /*! Create a queue.
00150     \brief Create a queue.
00151     \param len The length of the queue's buffer.
00152     \param flags Flags controlling the operation of the queue.
00153            Valid flags are QUEUE_READ_ATOMIC and QUEUE_WRITE_ATOMIC.
00154     \return A pointer to the context if created OK, else NULL. */
00155 queue_state_t *queue_create(int len, int flags);
00156 
00157 /*! Initialise a queue.
00158     \brief Initialise a queue.
00159     \param s The queue context. If is imperative that the context this
00160            points to is immediately followed by a buffer of the required
00161            size + 1 octet.
00162     \param len The length of the queue's buffer.
00163     \param flags Flags controlling the operation of the queue.
00164            Valid flags are QUEUE_READ_ATOMIC and QUEUE_WRITE_ATOMIC.
00165     \return A pointer to the context if OK, else NULL. */
00166 queue_state_t *queue_init(queue_state_t *s, int len, int flags);
00167 
00168 /*! Delete a queue.
00169     \brief Delete a queue.
00170     \param s The queue context.
00171     \return 0 if deleted OK, else -1. */
00172 int queue_delete(queue_state_t *s);
00173 
00174 #if defined(__cplusplus)
00175 }
00176 #endif
00177 
00178 #endif
00179 /*- End of file ------------------------------------------------------------*/

Generated on Tue Jul 24 11:29:28 2007 for libspandsp by  doxygen 1.5.2