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