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 Lesser General Public License version 2.1,
00014  * as 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 Lesser General Public License for more details.
00020  *
00021  * You should have received a copy of the GNU Lesser General Public
00022  * License along with this program; if not, write to the Free Software
00023  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00024  */
00025 
00026 /*! \file */
00027 
00028 /*! \page queue_page Queuing
00029 \section queue_page_sec_1 What does it do?
00030 This module provides lock free queuing for either octet streams or messages.
00031 Specifically, lock free means one thread can write and another can read without
00032 locking the queue. It does NOT means a free-for-all is possible, with many
00033 threads writing or many threads reading. Those things would require locking,
00034 to avoid conflicts between the multiple threads acting on one end of the queue.
00035 
00036 \section queue_page_sec_2 How does it work?
00037 ???.
00038 */
00039 
00040 #if !defined(_SPANDSP_QUEUE_H_)
00041 #define _SPANDSP_QUEUE_H_
00042 
00043 /*! Flag bit to indicate queue reads are atomic operations. This must be set
00044     if the queue is to be used with the message oriented functions. */
00045 #define QUEUE_READ_ATOMIC   0x0001
00046 /*! Flag bit to indicate queue writes are atomic operations. This must be set
00047     if the queue is to be used with the message oriented functions. */
00048 #define QUEUE_WRITE_ATOMIC  0x0002
00049 
00050 /*!
00051     Queue descriptor. This defines the working state for a single instance of
00052     a byte stream or message oriented queue.
00053 */
00054 typedef struct queue_state_s queue_state_t;
00055 
00056 #define QUEUE_STATE_T_SIZE(len) (sizeof(queue_state_t) + len + 1)
00057 
00058 #if defined(__cplusplus)
00059 extern "C"
00060 {
00061 #endif
00062 
00063 /*! Check if a queue is empty.
00064     \brief Check if a queue is empty.
00065     \param s The queue context.
00066     \return TRUE if empty, else FALSE. */
00067 SPAN_DECLARE(int) queue_empty(queue_state_t *s);
00068 
00069 /*! Check the available free space in a queue's buffer.
00070     \brief Check available free space.
00071     \param s The queue context.
00072     \return The number of bytes of free space. */
00073 SPAN_DECLARE(int) queue_free_space(queue_state_t *s);
00074 
00075 /*! Check the contents of a queue.
00076     \brief Check the contents of a queue.
00077     \param s The queue context.
00078     \return The number of bytes in the queue. */
00079 SPAN_DECLARE(int) queue_contents(queue_state_t *s);
00080 
00081 /*! Flush the contents of a queue.
00082     \brief Flush the contents of a queue.
00083     \param s The queue context. */
00084 SPAN_DECLARE(void) queue_flush(queue_state_t *s);
00085 
00086 /*! Copy bytes from a queue. This is similar to queue_read, but
00087     the data remains in the queue.
00088     \brief Copy bytes from a queue.
00089     \param s The queue context.
00090     \param buf The buffer into which the bytes will be read.
00091     \param len The length of the buffer.
00092     \return the number of bytes returned. */
00093 SPAN_DECLARE(int) queue_view(queue_state_t *s, uint8_t *buf, int len);
00094 
00095 /*! Read bytes from a queue.
00096     \brief Read bytes from a queue.
00097     \param s The queue context.
00098     \param buf The buffer into which the bytes will be read.
00099     \param len The length of the buffer.
00100     \return the number of bytes returned. */
00101 SPAN_DECLARE(int) queue_read(queue_state_t *s, uint8_t *buf, int len);
00102 
00103 /*! Read a byte from a queue.
00104     \brief Read a byte from a queue.
00105     \param s The queue context.
00106     \return the byte, or -1 if the queue is empty. */
00107 SPAN_DECLARE(int) queue_read_byte(queue_state_t *s);
00108 
00109 /*! Write bytes to a queue.
00110     \brief Write bytes to a queue.
00111     \param s The queue context.
00112     \param buf The buffer containing the bytes to be written.
00113     \param len The length of the buffer.
00114     \return the number of bytes actually written. */
00115 SPAN_DECLARE(int) queue_write(queue_state_t *s, const uint8_t *buf, int len);
00116 
00117 /*! Write a byte to a queue.
00118     \brief Write a byte to a queue.
00119     \param s The queue context.
00120     \param byte The byte to be written.
00121     \return the number of bytes actually written. */
00122 SPAN_DECLARE(int) queue_write_byte(queue_state_t *s, uint8_t byte);
00123 
00124 /*! Test the length of the message at the head of a queue.
00125     \brief Test message length.
00126     \param s The queue context.
00127     \return The length of the next message, in byte. If there are
00128             no messages in the queue, -1 is returned. */
00129 SPAN_DECLARE(int) queue_state_test_msg(queue_state_t *s);
00130 
00131 /*! Read a message from a queue. If the message is longer than the buffer
00132     provided, only the first len bytes of the message will be returned. The
00133     remainder of the message will be discarded.
00134     \brief Read a message from a queue.
00135     \param s The queue context.
00136     \param buf The buffer into which the message will be read.
00137     \param len The length of the buffer.
00138     \return The number of bytes returned. If there are
00139             no messages in the queue, -1 is returned. */
00140 SPAN_DECLARE(int) queue_read_msg(queue_state_t *s, uint8_t *buf, int len);
00141 
00142 /*! Write a message to a queue.
00143     \brief Write a message to a queue.
00144     \param s The queue context.
00145     \param buf The buffer from which the message will be written.
00146     \param len The length of the message.
00147     \return The number of bytes actually written. */
00148 SPAN_DECLARE(int) queue_write_msg(queue_state_t *s, const uint8_t *buf, int len);
00149 
00150 /*! Initialise a queue.
00151     \brief Initialise a queue.
00152     \param s The queue context. If is imperative that the context this
00153            points to is immediately followed by a buffer of the required
00154            size + 1 octet.
00155     \param len The length of the queue's buffer.
00156     \param flags Flags controlling the operation of the queue.
00157            Valid flags are QUEUE_READ_ATOMIC and QUEUE_WRITE_ATOMIC.
00158     \return A pointer to the context if OK, else NULL. */
00159 SPAN_DECLARE(queue_state_t *) queue_init(queue_state_t *s, int len, int flags);
00160 
00161 /*! Release a queue.
00162     \brief Release a queue.
00163     \param s The queue context.
00164     \return 0 if OK, else -1. */
00165 SPAN_DECLARE(int) queue_release(queue_state_t *s);
00166 
00167 /*! Free a queue.
00168     \brief Delete a queue.
00169     \param s The queue context.
00170     \return 0 if OK, else -1. */
00171 SPAN_DECLARE(int) queue_free(queue_state_t *s);
00172 
00173 #if defined(__cplusplus)
00174 }
00175 #endif
00176 
00177 #endif
00178 /*- End of file ------------------------------------------------------------*/

Generated on Thu Oct 18 15:28:01 2012 for spandsp by  doxygen 1.4.7