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.1.
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