1=pod 2 3=head1 NAME 4 5DEFINE_PRIORITY_QUEUE_OF, PRIORITY_QUEUE_OF, 6ossl_pqueue_TYPE_num, 7ossl_pqueue_TYPE_new, ossl_pqueue_TYPE_free, ossl_pqueue_TYPE_pop_free, 8ossl_pqueue_TYPE_reserve, 9ossl_pqueue_TYPE_push, ossl_pqueue_TYPE_peek, 10ossl_pqueue_TYPE_pop, ossl_pqueue_TYPE_remove 11- priority queue container 12 13=head1 SYNOPSIS 14 15=for openssl generic 16 17 #include "internal/priority_queue.h" 18 19 PRIORITY_QUEUE_OF(type); 20 21 DEFINE_PRIORITY_QUEUE_OF(NAME, TYPE) 22 23 size_t ossl_pqueue_TYPE_num(const PRIORITY_QUEUE_OF(type) *pq); 24 PRIORITY_QUEUE_OF(type) *ossl_pqueue_TYPE_new(int (*compare)(const type *, 25 const type *)); 26 void ossl_pqueue_TYPE_free(PRIORITY_QUEUE_OF(type) *pq); 27 void ossl_pqueue_TYPE_pop_free(PRIORITY_QUEUE_OF(type) *pq, 28 void (*free_func)(type *)); 29 int ossl_pqueue_TYPE_reserve(PRIORITY_QUEUE_OF(type) *pq, size_t n); 30 int ossl_pqueue_TYPE_push(PRIORITY_QUEUE_OF(type) *pq, type *data, 31 size_t *elem); 32 type *ossl_pqueue_TYPE_peek(const PRIORITY_QUEUE_OF(type) *pq); 33 type *ossl_pqueue_TYPE_pop(const PRIORITY_QUEUE_OF(type) *pq); 34 type *ossl_pqueue_TYPE_remove(const PRIORITY_QUEUE_OF(type) *pq, size_t elem); 35 36=head1 DESCRIPTION 37 38Create a type safe priority queue container. These macros define typesafe 39inline functions that wrap internal routines. In the description here, 40B<I<TYPE>> is used as a placeholder for any datatype. 41 42The PRIORITY_QUEUE_OF() macro returns the name for a priority queue 43of the specified B<I<TYPE>>. This is an opaque pointer to a structure 44declaration. 45 46DEFINE_PRIORITY_QUEUE_OF() creates a set of functions for a 47priority queue of B<I<TYPE>> elements. The type is represented by 48B<PRIORITY_QUEUE_OF>(B<I<TYPE>>) and each function name begins with 49B<ossl_pqueue_I<TYPE>_>. 50 51B<ossl_pqueue_I<TYPE>_num>() returns the number of elements in I<pq> 52or B<0> if I<pq> is NULL. 53 54B<ossl_pqueue_I<TYPE>_new>() allocates a new priority queue using 55comparison function I<compare>. It is an error for I<compare> to be NULL. 56The I<compare> function is called to order two elements, it should return 57B<-1> if the first element is less than the second, B<0> if they are 58equal and B<1> otherwise. 59 60B<ossl_pqueue_I<TYPE>_free>() frees up the I<pq> structure. It does I<not> 61free up any elements of I<pq>. After this call I<pq> is no longer valid. 62 63B<ossl_pqueue_I<TYPE>_pop_free>() frees up all elements of I<pq> and I<pq> 64itself. The free function freefunc() is called on each element to free it. 65After this call I<pq> is no longer valid. 66 67B<ossl_pqueue_I<TYPE>_reserve>() allocates additional memory in the I<pq> 68structure such that the next I<n> calls to B<ossl_pqueue_I<TYPE>_push>() 69will not fail or cause memory to be allocated or reallocated. If I<n> 70is zero, no additional space is reserved. On error I<pq> is unchanged. 71 72B<ossl_pqueue_I<TYPE>_push>() inserts a new element with value I<data> 73into the priority queue I<pq>. If not NULL, the function returns an index 74in B<*elem> which can be used to identify the element when calling 75B<ossl_pqueue_I<TYPE>_remove>(). 76 77B<ossl_pqueue_I<TYPE>_peek>() returns the data from the smallest element 78in I<pq>. 79 80B<ossl_pqueue_I<TYPE>_pop>() returns the data from the smallest element 81in I<pq> and removes that element from the priority queue. 82 83B<ossl_pqueue_I<TYPE>_remove>() returns and removes the specified element 84I<elem> from I<pq>. The index I<elem> must have been obtained from 85an earlier call made to B<ossl_pqueue_I<TYPE>_push>() with the same I<pq> 86argument. The index I<elem> is invalidated by this function. It is undefined 87what happens if an attempt to remove an element that isn't in the queue is 88made. 89 90=head1 RETURN VALUES 91 92B<ossl_pqueue_I<TYPE>_num>() returns the number of elements in the 93priority queue or B<0> if the passed priority queue is NULL. 94 95B<ossl_pqueue_I<TYPE>_new>() returns an empty priority queue or NULL if 96an error occurs. 97 98B<ossl_pqueue_I<TYPE>_free>() and B<ossl_pqueue_I<TYPE>_pop_free>() 99do not return values. 100 101B<ossl_pqueue_I<TYPE>_reserve>() returns B<1> on successful allocation 102of the required memory or B<0> on error. 103 104B<ossl_pqueue_I<TYPE>_push>() returns B<1> on success or B<0> on error. 105 106B<ossl_pqueue_I<TYPE>_peek>() and B<ossl_pqueue_I<TYPE>_pop>() return 107the data from the smallest element in the priority queue. 108 109B<ossl_pqueue_I<TYPE>_remove>() returns the data from the specified 110element. 111 112=head1 HISTORY 113 114The functions described here were all added in OpenSSL 3.2. 115 116=head1 COPYRIGHT 117 118Copyright 2022 The OpenSSL Project Authors. All Rights Reserved. 119 120Licensed under the Apache License 2.0 (the "License"). You may not use 121this file except in compliance with the License. You can obtain a copy 122in the file LICENSE in the source distribution or at 123L<https://www.openssl.org/source/license.html>. 124 125=cut 126