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.13 2008/01/31 13:34:40 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 /*! Flag bit to indicate queue reads are atomic operations. This must be set 00046 if the queue is to be used with the message oriented functions. */ 00047 #define QUEUE_READ_ATOMIC 0x0001 00048 /*! Flag bit to indicate queue writes are atomic operations. This must be set 00049 if the queue is to be used with the message oriented functions. */ 00050 #define QUEUE_WRITE_ATOMIC 0x0002 00051 00052 /*! 00053 Queue descriptor. This defines the working state for a single instance of 00054 a byte stream or message oriented queue. 00055 */ 00056 typedef struct 00057 { 00058 /*! \brief Flags indicating the mode of the queue. */ 00059 int flags; 00060 /*! \brief The length of the data buffer. */ 00061 int len; 00062 /*! \brief The buffer input pointer. */ 00063 volatile int iptr; 00064 /*! \brief The buffer output pointer. */ 00065 volatile int optr; 00066 /*! \brief The data buffer, sized at the time the structure is created. */ 00067 uint8_t data[]; 00068 } queue_state_t; 00069 00070 #if defined(__cplusplus) 00071 extern "C" 00072 { 00073 #endif 00074 00075 /*! Check if a queue is empty. 00076 \brief Check if a queue is empty. 00077 \param s The queue context. 00078 \return TRUE if empty, else FALSE. */ 00079 int queue_empty(queue_state_t *s); 00080 00081 /*! Check the available free space in a queue's buffer. 00082 \brief Check available free space. 00083 \param s The queue context. 00084 \return The number of bytes of free space. */ 00085 int queue_free_space(queue_state_t *s); 00086 00087 /*! Check the contents of a queue. 00088 \brief Check the contents of a queue. 00089 \param s The queue context. 00090 \return The number of bytes in the queue. */ 00091 int queue_contents(queue_state_t *s); 00092 00093 /*! Flush the contents of a queue. 00094 \brief Flush the contents of a queue. 00095 \param s The queue context. */ 00096 void queue_flush(queue_state_t *s); 00097 00098 /*! Copy bytes from a queue. This is similar to queue_read, but 00099 the data remains in the queue. 00100 \brief Copy bytes from a queue. 00101 \param s The queue context. 00102 \param buf The buffer into which the bytes will be read. 00103 \param len The length of the buffer. 00104 \return the number of bytes returned. */ 00105 int queue_view(queue_state_t *s, uint8_t *buf, int len); 00106 00107 /*! Read bytes from a queue. 00108 \brief Read bytes from a queue. 00109 \param s The queue context. 00110 \param buf The buffer into which the bytes will be read. 00111 \param len The length of the buffer. 00112 \return the number of bytes returned. */ 00113 int queue_read(queue_state_t *s, uint8_t *buf, int len); 00114 00115 /*! Read a byte from a queue. 00116 \brief Read a byte from a queue. 00117 \param s The queue context. 00118 \return the byte, or -1 if the queue is empty. */ 00119 int queue_read_byte(queue_state_t *s); 00120 00121 /*! Write bytes to a queue. 00122 \brief Write bytes to a queue. 00123 \param s The queue context. 00124 \param buf The buffer containing the bytes to be written. 00125 \param len The length of the buffer. 00126 \return the number of bytes actually written. */ 00127 int queue_write(queue_state_t *s, const uint8_t *buf, int len); 00128 00129 /*! Write a byte to a queue. 00130 \brief Write a byte to a queue. 00131 \param s The queue context. 00132 \param byte The byte to be written. 00133 \return the number of bytes actually written. */ 00134 int queue_write_byte(queue_state_t *s, uint8_t byte); 00135 00136 /*! Test the length of the message at the head of a queue. 00137 \brief Test message length. 00138 \param s The queue context. 00139 \return The length of the next message, in byte. If there are 00140 no messages in the queue, -1 is returned. */ 00141 int queue_state_test_msg(queue_state_t *s); 00142 00143 /*! Read a message from a queue. If the message is longer than the buffer 00144 provided, only the first len bytes of the message will be returned. The 00145 remainder of the message will be discarded. 00146 \brief Read a message from a queue. 00147 \param s The queue context. 00148 \param buf The buffer into which the message will be read. 00149 \param len The length of the buffer. 00150 \return The number of bytes returned. If there are 00151 no messages in the queue, -1 is returned. */ 00152 int queue_read_msg(queue_state_t *s, uint8_t *buf, int len); 00153 00154 /*! Write a message to a queue. 00155 \brief Write a message to a queue. 00156 \param s The queue context. 00157 \param buf The buffer from which the message will be written. 00158 \param len The length of the message. 00159 \return The number of bytes actually written. */ 00160 int queue_write_msg(queue_state_t *s, const uint8_t *buf, int len); 00161 00162 /*! Initialise a queue. 00163 \brief Initialise a queue. 00164 \param s The queue context. If is imperative that the context this 00165 points to is immediately followed by a buffer of the required 00166 size + 1 octet. 00167 \param len The length of the queue's buffer. 00168 \param flags Flags controlling the operation of the queue. 00169 Valid flags are QUEUE_READ_ATOMIC and QUEUE_WRITE_ATOMIC. 00170 \return A pointer to the context if OK, else NULL. */ 00171 queue_state_t *queue_init(queue_state_t *s, int len, int flags); 00172 00173 /*! Delete a queue. 00174 \brief Delete a queue. 00175 \param s The queue context. 00176 \return 0 if deleted OK, else -1. */ 00177 int queue_free(queue_state_t *s); 00178 00179 #if defined(__cplusplus) 00180 } 00181 #endif 00182 00183 #endif 00184 /*- End of file ------------------------------------------------------------*/