=pod

=head1 NAME

DEFINE_PRIORITY_QUEUE_OF, PRIORITY_QUEUE_OF,
ossl_pqueue_TYPE_num,
ossl_pqueue_TYPE_new, ossl_pqueue_TYPE_free, ossl_pqueue_TYPE_pop_free,
ossl_pqueue_TYPE_reserve,
ossl_pqueue_TYPE_push, ossl_pqueue_TYPE_peek,
ossl_pqueue_TYPE_pop, ossl_pqueue_TYPE_remove
- priority queue container

=head1 SYNOPSIS

=for openssl generic

 #include "internal/priority_queue.h"

 PRIORITY_QUEUE_OF(type);

 DEFINE_PRIORITY_QUEUE_OF(NAME, TYPE)

 size_t ossl_pqueue_TYPE_num(const PRIORITY_QUEUE_OF(type) *pq);
 PRIORITY_QUEUE_OF(type) *ossl_pqueue_TYPE_new(int (*compare)(const type *,
                                                              const type *));
 void ossl_pqueue_TYPE_free(PRIORITY_QUEUE_OF(type) *pq);
 void ossl_pqueue_TYPE_pop_free(PRIORITY_QUEUE_OF(type) *pq,
                                void (*free_func)(type *));
 int ossl_pqueue_TYPE_reserve(PRIORITY_QUEUE_OF(type) *pq, size_t n);
 int ossl_pqueue_TYPE_push(PRIORITY_QUEUE_OF(type) *pq, type *data,
                           size_t *elem);
 type *ossl_pqueue_TYPE_peek(const PRIORITY_QUEUE_OF(type) *pq);
 type *ossl_pqueue_TYPE_pop(const PRIORITY_QUEUE_OF(type) *pq);
 type *ossl_pqueue_TYPE_remove(const PRIORITY_QUEUE_OF(type) *pq, size_t elem);

=head1 DESCRIPTION

Create a type safe priority queue container.  These macros define typesafe
inline functions that wrap internal routines. In the description here,
B<I<TYPE>> is used as a placeholder for any datatype.

The PRIORITY_QUEUE_OF() macro returns the name for a priority queue
of the specified B<I<TYPE>>.  This is an opaque pointer to a structure
declaration.

DEFINE_PRIORITY_QUEUE_OF() creates a set of functions for a
priority queue of B<I<TYPE>> elements.  The type is represented by
B<PRIORITY_QUEUE_OF>(B<I<TYPE>>) and each function name begins with
B<ossl_pqueue_I<TYPE>_>.

B<ossl_pqueue_I<TYPE>_num>() returns the number of elements in I<pq>
or B<0> if I<pq> is NULL.

B<ossl_pqueue_I<TYPE>_new>() allocates a new priority queue using
comparison function I<compare>. It is an error for I<compare> to be NULL.
The I<compare> function is called to order two elements, it should return
B<-1> if the first element is less than the second, B<0> if they are
equal and B<1> otherwise.

B<ossl_pqueue_I<TYPE>_free>() frees up the I<pq> structure. It does I<not>
free up any elements of I<pq>. After this call I<pq> is no longer valid.

B<ossl_pqueue_I<TYPE>_pop_free>() frees up all elements of I<pq> and I<pq>
itself. The free function freefunc() is called on each element to free it.
After this call I<pq> is no longer valid.

B<ossl_pqueue_I<TYPE>_reserve>() allocates additional memory in the I<pq>
structure such that the next I<n> calls to B<ossl_pqueue_I<TYPE>_push>()
will not fail or cause memory to be allocated or reallocated. If I<n>
is zero, no additional space is reserved. On error I<pq> is unchanged.

B<ossl_pqueue_I<TYPE>_push>() inserts a new element with value I<data>
into the priority queue I<pq>. If not NULL, the function returns an index
in B<*elem> which can be used to identify the element when calling
B<ossl_pqueue_I<TYPE>_remove>().

B<ossl_pqueue_I<TYPE>_peek>() returns the data from the smallest element
in I<pq>.

B<ossl_pqueue_I<TYPE>_pop>() returns the data from the smallest element
in I<pq> and removes that element from the priority queue.

B<ossl_pqueue_I<TYPE>_remove>() returns and removes the specified element
I<elem> from I<pq>. The index I<elem> must have been obtained from
an earlier call made to B<ossl_pqueue_I<TYPE>_push>() with the same I<pq>
argument.  The index I<elem> is invalidated by this function.  It is undefined
what happens if an attempt to remove an element that isn't in the queue is
made.

=head1 RETURN VALUES

B<ossl_pqueue_I<TYPE>_num>() returns the number of elements in the
priority queue or B<0> if the passed priority queue is NULL.

B<ossl_pqueue_I<TYPE>_new>() returns an empty priority queue or NULL if
an error occurs.

B<ossl_pqueue_I<TYPE>_free>() and B<ossl_pqueue_I<TYPE>_pop_free>()
do not return values.

B<ossl_pqueue_I<TYPE>_reserve>() returns B<1> on successful allocation
of the required memory or B<0> on error.

B<ossl_pqueue_I<TYPE>_push>() returns B<1> on success or B<0> on error.

B<ossl_pqueue_I<TYPE>_peek>() and B<ossl_pqueue_I<TYPE>_pop>() return
the data from the smallest element in the priority queue.

B<ossl_pqueue_I<TYPE>_remove>() returns the data from the specified
element.

=head1 HISTORY

The functions described here were all added in OpenSSL 3.2.

=head1 COPYRIGHT

Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.

=cut