apr_queue.h revision 285830
1/* Licensed to the Apache Software Foundation (ASF) under one or more 2 * contributor license agreements. See the NOTICE file distributed with 3 * this work for additional information regarding copyright ownership. 4 * The ASF licenses this file to You under the Apache License, Version 2.0 5 * (the "License"); you may not use this file except in compliance with 6 * the License. You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17#ifndef APR_QUEUE_H 18#define APR_QUEUE_H 19 20/** 21 * @file apr_queue.h 22 * @brief Thread Safe FIFO bounded queue 23 * @note Since most implementations of the queue are backed by a condition 24 * variable implementation, it isn't available on systems without threads. 25 * Although condition variables are sometimes available without threads. 26 */ 27 28#include "apu.h" 29#include "apr_errno.h" 30#include "apr_pools.h" 31 32#if APR_HAS_THREADS 33 34#ifdef __cplusplus 35extern "C" { 36#endif /* __cplusplus */ 37 38/** 39 * @defgroup APR_Util_FIFO Thread Safe FIFO bounded queue 40 * @ingroup APR_Util 41 * @{ 42 */ 43 44/** 45 * opaque structure 46 */ 47typedef struct apr_queue_t apr_queue_t; 48 49/** 50 * create a FIFO queue 51 * @param queue The new queue 52 * @param queue_capacity maximum size of the queue 53 * @param a pool to allocate queue from 54 */ 55APU_DECLARE(apr_status_t) apr_queue_create(apr_queue_t **queue, 56 unsigned int queue_capacity, 57 apr_pool_t *a); 58 59/** 60 * push/add an object to the queue, blocking if the queue is already full 61 * 62 * @param queue the queue 63 * @param data the data 64 * @returns APR_EINTR the blocking was interrupted (try again) 65 * @returns APR_EOF the queue has been terminated 66 * @returns APR_SUCCESS on a successful push 67 */ 68APU_DECLARE(apr_status_t) apr_queue_push(apr_queue_t *queue, void *data); 69 70/** 71 * pop/get an object from the queue, blocking if the queue is already empty 72 * 73 * @param queue the queue 74 * @param data the data 75 * @returns APR_EINTR the blocking was interrupted (try again) 76 * @returns APR_EOF if the queue has been terminated 77 * @returns APR_SUCCESS on a successful pop 78 */ 79APU_DECLARE(apr_status_t) apr_queue_pop(apr_queue_t *queue, void **data); 80 81/** 82 * push/add an object to the queue, returning immediately if the queue is full 83 * 84 * @param queue the queue 85 * @param data the data 86 * @returns APR_EINTR the blocking operation was interrupted (try again) 87 * @returns APR_EAGAIN the queue is full 88 * @returns APR_EOF the queue has been terminated 89 * @returns APR_SUCCESS on a successful push 90 */ 91APU_DECLARE(apr_status_t) apr_queue_trypush(apr_queue_t *queue, void *data); 92 93/** 94 * pop/get an object to the queue, returning immediately if the queue is empty 95 * 96 * @param queue the queue 97 * @param data the data 98 * @returns APR_EINTR the blocking operation was interrupted (try again) 99 * @returns APR_EAGAIN the queue is empty 100 * @returns APR_EOF the queue has been terminated 101 * @returns APR_SUCCESS on a successful pop 102 */ 103APU_DECLARE(apr_status_t) apr_queue_trypop(apr_queue_t *queue, void **data); 104 105/** 106 * returns the size of the queue. 107 * 108 * @warning this is not threadsafe, and is intended for reporting/monitoring 109 * of the queue. 110 * @param queue the queue 111 * @returns the size of the queue 112 */ 113APU_DECLARE(unsigned int) apr_queue_size(apr_queue_t *queue); 114 115/** 116 * interrupt all the threads blocking on this queue. 117 * 118 * @param queue the queue 119 */ 120APU_DECLARE(apr_status_t) apr_queue_interrupt_all(apr_queue_t *queue); 121 122/** 123 * terminate the queue, sending an interrupt to all the 124 * blocking threads 125 * 126 * @param queue the queue 127 */ 128APU_DECLARE(apr_status_t) apr_queue_term(apr_queue_t *queue); 129 130#ifdef __cplusplus 131} 132#endif 133 134/** @} */ 135 136#endif /* APR_HAS_THREADS */ 137 138#endif /* APRQUEUE_H */ 139