apr_queue.h revision 262253
1251876Speter/* Licensed to the Apache Software Foundation (ASF) under one or more 2251876Speter * contributor license agreements. See the NOTICE file distributed with 3251876Speter * this work for additional information regarding copyright ownership. 4251876Speter * The ASF licenses this file to You under the Apache License, Version 2.0 5251876Speter * (the "License"); you may not use this file except in compliance with 6251876Speter * the License. You may obtain a copy of the License at 7251876Speter * 8251876Speter * http://www.apache.org/licenses/LICENSE-2.0 9251876Speter * 10251876Speter * Unless required by applicable law or agreed to in writing, software 11251876Speter * distributed under the License is distributed on an "AS IS" BASIS, 12251876Speter * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13251876Speter * See the License for the specific language governing permissions and 14251876Speter * limitations under the License. 15251876Speter */ 16251876Speter 17251876Speter#ifndef APR_QUEUE_H 18251876Speter#define APR_QUEUE_H 19251876Speter 20251876Speter/** 21251876Speter * @file apr_queue.h 22251876Speter * @brief Thread Safe FIFO bounded queue 23251876Speter * @note Since most implementations of the queue are backed by a condition 24251876Speter * variable implementation, it isn't available on systems without threads. 25262253Speter * Although condition variables are sometimes available without threads. 26251876Speter */ 27251876Speter 28251876Speter#include "apu.h" 29251876Speter#include "apr_errno.h" 30251876Speter#include "apr_pools.h" 31251876Speter 32251876Speter#if APR_HAS_THREADS 33251876Speter 34251876Speter#ifdef __cplusplus 35251876Speterextern "C" { 36251876Speter#endif /* __cplusplus */ 37251876Speter 38251876Speter/** 39251876Speter * @defgroup APR_Util_FIFO Thread Safe FIFO bounded queue 40251876Speter * @ingroup APR_Util 41251876Speter * @{ 42251876Speter */ 43251876Speter 44251876Speter/** 45251876Speter * opaque structure 46251876Speter */ 47251876Spetertypedef struct apr_queue_t apr_queue_t; 48251876Speter 49251876Speter/** 50251876Speter * create a FIFO queue 51251876Speter * @param queue The new queue 52251876Speter * @param queue_capacity maximum size of the queue 53251876Speter * @param a pool to allocate queue from 54251876Speter */ 55251876SpeterAPU_DECLARE(apr_status_t) apr_queue_create(apr_queue_t **queue, 56251876Speter unsigned int queue_capacity, 57251876Speter apr_pool_t *a); 58251876Speter 59251876Speter/** 60251876Speter * push/add an object to the queue, blocking if the queue is already full 61251876Speter * 62251876Speter * @param queue the queue 63251876Speter * @param data the data 64251876Speter * @returns APR_EINTR the blocking was interrupted (try again) 65251876Speter * @returns APR_EOF the queue has been terminated 66251876Speter * @returns APR_SUCCESS on a successful push 67251876Speter */ 68251876SpeterAPU_DECLARE(apr_status_t) apr_queue_push(apr_queue_t *queue, void *data); 69251876Speter 70251876Speter/** 71251876Speter * pop/get an object from the queue, blocking if the queue is already empty 72251876Speter * 73251876Speter * @param queue the queue 74251876Speter * @param data the data 75251876Speter * @returns APR_EINTR the blocking was interrupted (try again) 76251876Speter * @returns APR_EOF if the queue has been terminated 77251876Speter * @returns APR_SUCCESS on a successful pop 78251876Speter */ 79251876SpeterAPU_DECLARE(apr_status_t) apr_queue_pop(apr_queue_t *queue, void **data); 80251876Speter 81251876Speter/** 82251876Speter * push/add an object to the queue, returning immediately if the queue is full 83251876Speter * 84251876Speter * @param queue the queue 85251876Speter * @param data the data 86251876Speter * @returns APR_EINTR the blocking operation was interrupted (try again) 87251876Speter * @returns APR_EAGAIN the queue is full 88251876Speter * @returns APR_EOF the queue has been terminated 89251876Speter * @returns APR_SUCCESS on a successful push 90251876Speter */ 91251876SpeterAPU_DECLARE(apr_status_t) apr_queue_trypush(apr_queue_t *queue, void *data); 92251876Speter 93251876Speter/** 94251876Speter * pop/get an object to the queue, returning immediately if the queue is empty 95251876Speter * 96251876Speter * @param queue the queue 97251876Speter * @param data the data 98251876Speter * @returns APR_EINTR the blocking operation was interrupted (try again) 99251876Speter * @returns APR_EAGAIN the queue is empty 100251876Speter * @returns APR_EOF the queue has been terminated 101253734Speter * @returns APR_SUCCESS on a successful pop 102251876Speter */ 103251876SpeterAPU_DECLARE(apr_status_t) apr_queue_trypop(apr_queue_t *queue, void **data); 104251876Speter 105251876Speter/** 106251876Speter * returns the size of the queue. 107251876Speter * 108251876Speter * @warning this is not threadsafe, and is intended for reporting/monitoring 109251876Speter * of the queue. 110251876Speter * @param queue the queue 111251876Speter * @returns the size of the queue 112251876Speter */ 113251876SpeterAPU_DECLARE(unsigned int) apr_queue_size(apr_queue_t *queue); 114251876Speter 115251876Speter/** 116251876Speter * interrupt all the threads blocking on this queue. 117251876Speter * 118251876Speter * @param queue the queue 119251876Speter */ 120251876SpeterAPU_DECLARE(apr_status_t) apr_queue_interrupt_all(apr_queue_t *queue); 121251876Speter 122251876Speter/** 123251876Speter * terminate the queue, sending an interrupt to all the 124251876Speter * blocking threads 125251876Speter * 126251876Speter * @param queue the queue 127251876Speter */ 128251876SpeterAPU_DECLARE(apr_status_t) apr_queue_term(apr_queue_t *queue); 129251876Speter 130251876Speter#ifdef __cplusplus 131251876Speter} 132251876Speter#endif 133251876Speter 134251876Speter/** @} */ 135251876Speter 136251876Speter#endif /* APR_HAS_THREADS */ 137251876Speter 138251876Speter#endif /* APRQUEUE_H */ 139