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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
18 * @file cache_pqueue.h
19 * @brief Cache Priority Queue function declarations
21 * @defgroup MOD_CACHE_QUEUE Priority Queue
26 #ifndef CACHE_PQUEUE_H
27 #define CACHE_PQUEUE_H
30 #include <apr_errno.h>
40 /** the cache priority queue handle */
41 typedef struct cache_pqueue_t cache_pqueue_t;
44 * callback function to assign a priority for a element
45 * @param a the element
46 * @return the score (the lower the score the longer it is kept int the queue)
48 typedef long (*cache_pqueue_set_priority)(long queue_clock, void *a);
49 typedef long (*cache_pqueue_get_priority)(void *a);
51 /** callback function to get a position of a element */
52 typedef apr_ssize_t (*cache_pqueue_getpos)(void *a);
55 * callback function to set a position of a element
56 * @param a the element
57 * @param pos the position to set it to
59 typedef void (*cache_pqueue_setpos)(void *a, apr_ssize_t pos);
61 /** debug callback function to print a entry */
62 typedef void (*cache_pqueue_print_entry)(FILE *out, void *a);
65 * initialize the queue
67 * @param n the initial estimate of the number of queue items for which memory
68 * should be preallocated
69 * @param pri the callback function to run to assign a score to a element
70 * @param get the callback function to get the current element's position
71 * @param set the callback function to set the current element's position
73 * @return the handle or NULL for insufficent memory
75 cache_pqueue_t *cache_pq_init(apr_ssize_t n,
76 cache_pqueue_get_priority pri,
77 cache_pqueue_getpos get,
78 cache_pqueue_setpos set);
80 * free all memory used by the queue
83 void cache_pq_free(cache_pqueue_t *q);
85 * return the size of the queue.
88 apr_ssize_t cache_pq_size(cache_pqueue_t *q);
91 * insert an item into the queue.
94 * @return APR_SUCCESS on success
96 apr_status_t cache_pq_insert(cache_pqueue_t *q, void *d);
99 * move a existing entry to a different priority
101 * @param old the old priority
104 void cache_pq_change_priority(cache_pqueue_t *q,
110 * pop the highest-ranking item from the queue.
112 * @return NULL on error, otherwise the entry
114 void *cache_pq_pop(cache_pqueue_t *q);
117 * remove an item from the queue.
120 * @return APR_SUCCESS on success
122 apr_status_t cache_pq_remove(cache_pqueue_t *q, void *d);
125 * access highest-ranking item without removing it.
127 * @return NULL on error, otherwise the entry
129 void *cache_pq_peek(cache_pqueue_t *q);
134 * DEBUG function only
136 * @param out the output handle
137 * @param print the callback function to print the entry
139 void cache_pq_print(cache_pqueue_t *q,
141 cache_pqueue_print_entry print);
144 * dump the queue and it's internal structure
146 * debug function only
148 * @param out the output handle
149 * @param print the callback function to print the entry
151 void cache_pq_dump(cache_pqueue_t *q,
153 cache_pqueue_print_entry print);
156 * checks that the pq is in the right order, etc
158 * debug function only
161 int cache_pq_is_valid(cache_pqueue_t *q);
167 #endif /* !CACHE_PQUEUE_H */