rubbos/app/httpd-2.0.64/modules/experimental/cache_pqueue.h

   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 CACHE_PQUEUE_H
  18 #define CACHE_PQUEUE_H
  19
  20 #include <apr.h>
  21 #include <apr_errno.h>
  22
  23 #if APR_HAVE_STDIO_H
  24 #include <stdio.h>
  25 #endif
  26
  27 #ifdef __cplusplus
  28 extern "C" {
  29 #endif
  30
  31 /** the cache priority queue handle */
  32 typedef struct cache_pqueue_t cache_pqueue_t;
  33
  34 /**
  35  * callback function to assign a priority for a element
  36  * @param a the element
  37  * @return  the score (the lower the score the longer it is kept int the queue)
  38  */
  39 typedef long (*cache_pqueue_set_priority)(long queue_clock, void *a);
  40 typedef long (*cache_pqueue_get_priority)(void *a);
  41
  42 /** callback function to get a position of a element */
  43 typedef apr_ssize_t (*cache_pqueue_getpos)(void *a);
  44
  45 /**
  46  * callback function to set a position of a element
  47  * @param a   the element
  48  * @param pos the position to set it to
  49  */
  50 typedef void (*cache_pqueue_setpos)(void *a, apr_ssize_t pos);
  51
  52 /** debug callback function to print a entry */
  53 typedef void (*cache_pqueue_print_entry)(FILE *out, void *a);
  54
  55 /**
  56  * initialize the queue
  57  *
  58  * @param n the initial estimate of the number of queue items for which memory
  59  *          should be preallocated
  60  * @param pri the callback function to run to assign a score to a element
  61  * @param get the callback function to get the current element's position
  62  * @param set the callback function to set the current element's position
  63  *
  64  * @Return the handle or NULL for insufficent memory
  65  */
  66 cache_pqueue_t *cache_pq_init(apr_ssize_t n,
  67                               cache_pqueue_get_priority pri,
  68                               cache_pqueue_getpos get,
  69                               cache_pqueue_setpos set);
  70 /**
  71  * free all memory used by the queue
  72  * @param q the queue
  73  */
  74 void cache_pq_free(cache_pqueue_t *q);
  75 /**
  76  * return the size of the queue.
  77  * @param q the queue
  78  */
  79 apr_ssize_t cache_pq_size(cache_pqueue_t *q);
  80
  81 /**
  82  * insert an item into the queue.
  83  * @param q the queue
  84  * @param d the item
  85  * @return APR_SUCCESS on success
  86  */
  87 apr_status_t cache_pq_insert(cache_pqueue_t *q, void *d);
  88
  89 /*
  90  * move a existing entry to a different priority
  91  * @param q the queue
  92  * @param old the old priority
  93  * @param d the entry
  94  */
  95 void cache_pq_change_priority(cache_pqueue_t *q,
  96                               long old_priority,
  97                               long new_priority,
  98                               void *d);
  99
 100 /**
 101  * pop the highest-ranking item from the queue.
 102  * @param p the queue
 103  * @param d where to copy the entry to
 104  * @return NULL on error, otherwise the entry
 105  */
 106 void *cache_pq_pop(cache_pqueue_t *q);
 107
 108 /**
 109  * remove an item from the queue.
 110  * @param p the queue
 111  * @param d the entry
 112  * @return APR_SUCCESS on success
 113  */
 114 apr_status_t cache_pq_remove(cache_pqueue_t *q, void *d);
 115
 116 /**
 117  * access highest-ranking item without removing it.
 118  * @param q the queue
 119  * @param d the entry
 120  * @return NULL on error, otherwise the entry
 121  */
 122 void *cache_pq_peek(cache_pqueue_t *q);
 123
 124 /**
 125  * print the queue
 126  * @internal
 127  * DEBUG function only
 128  * @param q the queue
 129  * @param out the output handle
 130  * @param the callback function to print the entry
 131  */
 132 void cache_pq_print(cache_pqueue_t *q,
 133                     FILE *out,
 134                     cache_pqueue_print_entry print);
 135
 136 /**
 137  * dump the queue and it's internal structure
 138  * @internal
 139  * debug function only
 140  * @param q the queue
 141  * @param out the output handle
 142  * @param the callback function to print the entry
 143  */
 144 void cache_pq_dump(cache_pqueue_t *q,
 145                    FILE *out,
 146                    cache_pqueue_print_entry print);
 147
 148 /**
 149  * checks that the pq is in the right order, etc
 150  * @internal
 151  * debug function only
 152  * @param q the queue
 153  */
 154 int cache_pq_is_valid(cache_pqueue_t *q);
 155
 156 #ifdef __cplusplus
 157 }
 158 #endif
 159
 160 #endif /* !CACHE_PQUEUE_H */