Change all references to OpenSSL 3.1 to OpenSSL 3.2 in the master branch

[thirdparty/openssl.git] / doc / internal / man3 / OSSL_EVENT.pod

=pod

=head1 NAME

OSSL_EVENT_QUEUE, OSSL_EVENT, OSSL_EVENT_SUBSCRIPTION, ossl_event_callback_fn,
ossl_event_queue_add, ossl_event_queue_add_new, ossl_event_free,
ossl_event_get_type, ossl_event_get_priority, ossl_event_get_when,
ossl_event_get0_payload,
ossl_event_queue_new, ossl_event_queue_free,
ossl_event_queue_schedule, ossl_event_queue_delete,
ossl_event_time_until, ossl_event_queue_time_until_next,
ossl_event_queue_postpone_until,
ossl_event_queue_get1_next_event
- event and timer queue

=head1 SYNOPSIS

 #include "internal/event_queue.h"

 typedef OSSL_EVENT;
 typedef OSSL_EVENT_QUEUE;
 typedef OSSL_EVENT_SUBSCRIPTION;

 typedef int ossl_event_callback_fn(OSSL_EVENT *event, void *callback_data);

 OSSL_EVENT_QUEUE *ossl_event_queue_new(void);
 void ossl_event_queue_free(OSSL_EVENT_QUEUE *queue);

 int ossl_event_queue_add(OSSL_EVENT_QUEUE *queue, OSSL_EVENT *event,
                          uint32_t type, uint32_t priority,
                          OSSL_TIME when, void *ctx,
                          void *payload, size_t payload_size);
 OSSL_EVENT *ossl_event_queue_add_new(OSSL_EVENT_QUEUE *queue,
                                      uint32_t type, uint32_t priority,
                                      OSSL_TIME when, void *ctx,
                                      void *payload, size_t payload_size);
 void ossl_event_free(OSSL_EVENT *event);

 uint32_t ossl_event_get_type(const OSSL_EVENT *event);
 uint32_t ossl_event_get_priority(const OSSL_EVENT *event);
 OSSL_TIME ossl_event_get_when(const OSSL_EVENT *event);
 void *ossl_event_get0_payload(const OSSL_EVENT *event, size_t *length);

 int ossl_event_queue_schedule(OSSL_EVENT_QUEUE *queue, OSSL_EVENT *event);
 int ossl_event_queue_delete(OSSL_EVENT_QUEUE *queue, OSSL_EVENT *event);

 OSSL_TIME ossl_event_time_until(OSSL_EVENT *event);
 OSSL_TIME ossl_event_queue_time_until_next(const OSSL_EVENT_QUEUE *queue);

 int ossl_event_queue_postpone_until(OSSL_EVENT_QUEUE *queue,
                                     OSSL_EVENT *event,
                                     OSSL_TIME when);

 int ossl_event_queue_get1_next_event(OSSL_EVENT_QUEUE *queue,
                                      OSSL_EVENT **event);

=head1 DESCRIPTION

These functions implement an event queue.

=head2 Event

An event is a small structure, B<OSSL_EVENT>, carrying information:

=over 4

=item type

A mandatory event type, which is a simple numeric identity, the
meaning of which is not known by the event functionality itself.

=item priority

A mandatory nonnegative integral quantity.  The lower the priority the earlier
the event will be processed.

=item when

An optional time indicating when the event could be triggered.  Events are
guaranteed to not trigger before their time.

=item context

A reference to user supplied contextual informaton.  The event queue passes
this to callbacks and never dereferences the pointer.

=item payload, payload_size

A reference to some event specific data of a specified length.

=back

The event itself is designed for a single synchronous thread, i.e. cannot be
shared by multiple threads.  The diverse objects it refers to may, however,
be shared by multiple threads, at the discretion of the functions in the
method structure.

Once populated, the event type, the references to event context, and the
reference to the destructor function are considered immutable, up until the
event structure is destroyed.

The reference to the auxilliary identifying material or to the payload,
however, are considered mutable.  Any event handler may "steal" them and
replace the reference to them in the event structure with NULL.  Stealing
must be done with much care.

Events may be embedded in another structure or as a static variable.
Events may also be dynamically allocated.

B<ossl_event_queue_add> initialises/reinitialises a static event object
with the specified parameters and adds it to the event queue I<queue>.
The event object I<event> has it's fields set to the passed parameters.

B<ossl_event_queue_add_new> allocates a new timer event on the heap
and initialises and adds it as per B<ossl_event_queue_add>.  A pointer to the
new event is returned on success and NULL is returned on error.

B<ossl_event_free> frees an allocated event returned by B<ossl_event_new>.
Does nothing if passed a pointer to a static event object which was initialised
using B<ossl_event_set>.

B<ossl_event_time_until> returns the time until I<event> would
trigger.  The event need not be part of an event queue.

B<ossl_event_queue_postpone_until> reschedules the I<event>, which must
be scheduled as part of timer event queue I<queue>, so that it will activate
at time I<when>.

B<ossl_event_get_type> returns the type of the I<event>.

B<ossl_event_get_priority> returns the priority of the I<event>.

B<ossl_event_get_when> returns the triggering time of the I<event>.

B<ossl_event_get0_payload> returns the payload for the I<event>, the length
of the payload is stored in I<length>.

=head2 Event queue

B<OSSL_EVENT_QUEUE> is an opaque structure that defines a timer based
event queue.  Event queue objects can only be dynamically allocated.

B<ossl_event_queue_new> returns a newly allocated event queue object.

B<ossl_event_queue_free> frees a event queue object returned by
B<ossl_event_queue_new>.

B<ossl_event_queue_schedule> adds the specified I<event> to the timer
event queue I<queue>.  The I<event> must not already be contained by any
timer event queue including I<queue>.

B<ossl_event_queue_delete> removes the specified I<event> from the
timer event queue I<queue>.  The event must have previously been added
to I<queue> using the B<ossl_event_queue_schedule> call and must not yet
have triggered.

B<ossl_event_queue_time_until_next> returns the time until the next
event in the timer event queue I<queue> is scheduled to trigger.

B<ossl_event_queue_get1_next_event> gets the next event to process.
The event is removed from the event queue and, if dynamically allocated,
must be freed by the caller.  A NULL event is returned if there is no event
to process.

=head1 RETURN VALUES

B<ossl_event_queue_new> returns a new timer queue or NULL on failure.

B<ossl_event_new> returns a new event or NULL on failure.

B<ossl_event_get_type>, B<ossl_event_get_priority> and
B<ossl_event_get_when> return the corresponding event field.

B<ossl_event_get0_payload> returns a pointer to the event's payload.

B<ossl_event_queue_add>, B<ossl_event_queue_remove>,
B<ossl_event_queue_postpone_until> and
B<ossl_event_queue_get1_next_event> return 1 on success and 0 on failure.

B<ossl_event_time_until> and B<ossl_event_queue_time_until_next>
return a time until the next event or B<OSSL_TIME_INFINITY> if there is no
next event.

=head1 SEE ALSO

L<OSSL_TIME(3)>

=head1 HISTORY

This functionality was added to 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