apr_queue.h revision 262253 
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