Apache Portable Runtime
|
00001 /* Licensed to the Apache Software Foundation (ASF) under one or more 00002 * contributor license agreements. See the NOTICE file distributed with 00003 * this work for additional information regarding copyright ownership. 00004 * The ASF licenses this file to You under the Apache License, Version 2.0 00005 * (the "License"); you may not use this file except in compliance with 00006 * the License. You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 00017 #ifndef APR_QUEUE_H 00018 #define APR_QUEUE_H 00019 00020 /** 00021 * @file apr_queue.h 00022 * @brief Thread Safe FIFO bounded queue 00023 * @note Since most implementations of the queue are backed by a condition 00024 * variable implementation, it isn't available on systems without threads. 00025 * Although condition variables are some times available without threads. 00026 */ 00027 00028 #include "apu.h" 00029 #include "apr_errno.h" 00030 #include "apr_pools.h" 00031 00032 #if APR_HAS_THREADS 00033 00034 #ifdef __cplusplus 00035 extern "C" { 00036 #endif /* __cplusplus */ 00037 00038 /** 00039 * @defgroup APR_Util_FIFO Thread Safe FIFO bounded queue 00040 * @ingroup APR_Util 00041 * @{ 00042 */ 00043 00044 /** 00045 * opaque structure 00046 */ 00047 typedef struct apr_queue_t apr_queue_t; 00048 00049 /** 00050 * create a FIFO queue 00051 * @param queue The new queue 00052 * @param queue_capacity maximum size of the queue 00053 * @param a pool to allocate queue from 00054 */ 00055 APU_DECLARE(apr_status_t) apr_queue_create(apr_queue_t **queue, 00056 unsigned int queue_capacity, 00057 apr_pool_t *a); 00058 00059 /** 00060 * push/add an object to the queue, blocking if the queue is already full 00061 * 00062 * @param queue the queue 00063 * @param data the data 00064 * @returns APR_EINTR the blocking was interrupted (try again) 00065 * @returns APR_EOF the queue has been terminated 00066 * @returns APR_SUCCESS on a successful push 00067 */ 00068 APU_DECLARE(apr_status_t) apr_queue_push(apr_queue_t *queue, void *data); 00069 00070 /** 00071 * pop/get an object from the queue, blocking if the queue is already empty 00072 * 00073 * @param queue the queue 00074 * @param data the data 00075 * @returns APR_EINTR the blocking was interrupted (try again) 00076 * @returns APR_EOF if the queue has been terminated 00077 * @returns APR_SUCCESS on a successful pop 00078 */ 00079 APU_DECLARE(apr_status_t) apr_queue_pop(apr_queue_t *queue, void **data); 00080 00081 /** 00082 * push/add an object to the queue, returning immediately if the queue is full 00083 * 00084 * @param queue the queue 00085 * @param data the data 00086 * @returns APR_EINTR the blocking operation was interrupted (try again) 00087 * @returns APR_EAGAIN the queue is full 00088 * @returns APR_EOF the queue has been terminated 00089 * @returns APR_SUCCESS on a successful push 00090 */ 00091 APU_DECLARE(apr_status_t) apr_queue_trypush(apr_queue_t *queue, void *data); 00092 00093 /** 00094 * pop/get an object to the queue, returning immediately if the queue is empty 00095 * 00096 * @param queue the queue 00097 * @param data the data 00098 * @returns APR_EINTR the blocking operation was interrupted (try again) 00099 * @returns APR_EAGAIN the queue is empty 00100 * @returns APR_EOF the queue has been terminated 00101 * @returns APR_SUCCESS on a successful push 00102 */ 00103 APU_DECLARE(apr_status_t) apr_queue_trypop(apr_queue_t *queue, void **data); 00104 00105 /** 00106 * returns the size of the queue. 00107 * 00108 * @warning this is not threadsafe, and is intended for reporting/monitoring 00109 * of the queue. 00110 * @param queue the queue 00111 * @returns the size of the queue 00112 */ 00113 APU_DECLARE(unsigned int) apr_queue_size(apr_queue_t *queue); 00114 00115 /** 00116 * interrupt all the threads blocking on this queue. 00117 * 00118 * @param queue the queue 00119 */ 00120 APU_DECLARE(apr_status_t) apr_queue_interrupt_all(apr_queue_t *queue); 00121 00122 /** 00123 * terminate the queue, sending an interrupt to all the 00124 * blocking threads 00125 * 00126 * @param queue the queue 00127 */ 00128 APU_DECLARE(apr_status_t) apr_queue_term(apr_queue_t *queue); 00129 00130 #ifdef __cplusplus 00131 } 00132 #endif 00133 00134 /** @} */ 00135 00136 #endif /* APR_HAS_THREADS */ 00137 00138 #endif /* APRQUEUE_H */