Apache Portable Runtime
apr_queue.h
Go to the documentation of this file.
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
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 APR_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 APR_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 APR_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 APR_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 APR_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 APR_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 APR_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 APR_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 */
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Defines