1=pod 2 3=head1 NAME 4 5OSSL_EVENT_QUEUE, OSSL_EVENT, OSSL_EVENT_SUBSCRIPTION, ossl_event_callback_fn, 6ossl_event_queue_add, ossl_event_queue_add_new, ossl_event_free, 7ossl_event_get_type, ossl_event_get_priority, ossl_event_get_when, 8ossl_event_get0_payload, 9ossl_event_queue_new, ossl_event_queue_free, 10ossl_event_queue_schedule, ossl_event_queue_delete, 11ossl_event_time_until, ossl_event_queue_time_until_next, 12ossl_event_queue_postpone_until, 13ossl_event_queue_get1_next_event 14- event and timer queue 15 16=head1 SYNOPSIS 17 18 #include "internal/event_queue.h" 19 20 typedef OSSL_EVENT; 21 typedef OSSL_EVENT_QUEUE; 22 typedef OSSL_EVENT_SUBSCRIPTION; 23 24 typedef int ossl_event_callback_fn(OSSL_EVENT *event, void *callback_data); 25 26 OSSL_EVENT_QUEUE *ossl_event_queue_new(void); 27 void ossl_event_queue_free(OSSL_EVENT_QUEUE *queue); 28 29 int ossl_event_queue_add(OSSL_EVENT_QUEUE *queue, OSSL_EVENT *event, 30 uint32_t type, uint32_t priority, 31 OSSL_TIME when, void *ctx, 32 void *payload, size_t payload_size); 33 OSSL_EVENT *ossl_event_queue_add_new(OSSL_EVENT_QUEUE *queue, 34 uint32_t type, uint32_t priority, 35 OSSL_TIME when, void *ctx, 36 void *payload, size_t payload_size); 37 void ossl_event_free(OSSL_EVENT *event); 38 39 uint32_t ossl_event_get_type(const OSSL_EVENT *event); 40 uint32_t ossl_event_get_priority(const OSSL_EVENT *event); 41 OSSL_TIME ossl_event_get_when(const OSSL_EVENT *event); 42 void *ossl_event_get0_payload(const OSSL_EVENT *event, size_t *length); 43 44 int ossl_event_queue_schedule(OSSL_EVENT_QUEUE *queue, OSSL_EVENT *event); 45 int ossl_event_queue_delete(OSSL_EVENT_QUEUE *queue, OSSL_EVENT *event); 46 47 OSSL_TIME ossl_event_time_until(OSSL_EVENT *event); 48 OSSL_TIME ossl_event_queue_time_until_next(const OSSL_EVENT_QUEUE *queue); 49 50 int ossl_event_queue_postpone_until(OSSL_EVENT_QUEUE *queue, 51 OSSL_EVENT *event, 52 OSSL_TIME when); 53 54 int ossl_event_queue_get1_next_event(OSSL_EVENT_QUEUE *queue, 55 OSSL_EVENT **event); 56 57=head1 DESCRIPTION 58 59These functions implement an event queue. 60 61=head2 Event 62 63An event is a small structure, B<OSSL_EVENT>, carrying information: 64 65=over 4 66 67=item type 68 69A mandatory event type, which is a simple numeric identity, the 70meaning of which is not known by the event functionality itself. 71 72=item priority 73 74A mandatory nonnegative integral quantity. The lower the priority the earlier 75the event will be processed. 76 77=item when 78 79An optional time indicating when the event could be triggered. Events are 80guaranteed to not trigger before their time. 81 82=item context 83 84A reference to user supplied contextual information. The event queue passes 85this to callbacks and never dereferences the pointer. 86 87=item payload, payload_size 88 89A reference to some event specific data of a specified length. 90 91=back 92 93The event itself is designed for a single synchronous thread, i.e. cannot be 94shared by multiple threads. The diverse objects it refers to may, however, 95be shared by multiple threads, at the discretion of the functions in the 96method structure. 97 98Once populated, the event type, the references to event context, and the 99reference to the destructor function are considered immutable, up until the 100event structure is destroyed. 101 102The reference to the auxiliary identifying material or to the payload, 103however, are considered mutable. Any event handler may "steal" them and 104replace the reference to them in the event structure with NULL. Stealing 105must be done with much care. 106 107Events may be embedded in another structure or as a static variable. 108Events may also be dynamically allocated. 109 110B<ossl_event_queue_add> initialises/reinitialises a static event object 111with the specified parameters and adds it to the event queue I<queue>. 112The event object I<event> has it's fields set to the passed parameters. 113 114B<ossl_event_queue_add_new> allocates a new timer event on the heap 115and initialises and adds it as per B<ossl_event_queue_add>. A pointer to the 116new event is returned on success and NULL is returned on error. 117 118B<ossl_event_free> frees an allocated event returned by B<ossl_event_new>. 119Does nothing if passed a pointer to a static event object which was initialised 120using B<ossl_event_set>. 121 122B<ossl_event_time_until> returns the time until I<event> would 123trigger. The event need not be part of an event queue. 124 125B<ossl_event_queue_postpone_until> reschedules the I<event>, which must 126be scheduled as part of timer event queue I<queue>, so that it will activate 127at time I<when>. 128 129B<ossl_event_get_type> returns the type of the I<event>. 130 131B<ossl_event_get_priority> returns the priority of the I<event>. 132 133B<ossl_event_get_when> returns the triggering time of the I<event>. 134 135B<ossl_event_get0_payload> returns the payload for the I<event>, the length 136of the payload is stored in I<length>. 137 138=head2 Event queue 139 140B<OSSL_EVENT_QUEUE> is an opaque structure that defines a timer based 141event queue. Event queue objects can only be dynamically allocated. 142 143B<ossl_event_queue_new> returns a newly allocated event queue object. 144 145B<ossl_event_queue_free> frees a event queue object returned by 146B<ossl_event_queue_new>. 147 148B<ossl_event_queue_schedule> adds the specified I<event> to the timer 149event queue I<queue>. The I<event> must not already be contained by any 150timer event queue including I<queue>. 151 152B<ossl_event_queue_delete> removes the specified I<event> from the 153timer event queue I<queue>. The event must have previously been added 154to I<queue> using the B<ossl_event_queue_schedule> call and must not yet 155have triggered. 156 157B<ossl_event_queue_time_until_next> returns the time until the next 158event in the timer event queue I<queue> is scheduled to trigger. 159 160B<ossl_event_queue_get1_next_event> gets the next event to process. 161The event is removed from the event queue and, if dynamically allocated, 162must be freed by the caller. A NULL event is returned if there is no event 163to process. 164 165=head1 RETURN VALUES 166 167B<ossl_event_queue_new> returns a new timer queue or NULL on failure. 168 169B<ossl_event_new> returns a new event or NULL on failure. 170 171B<ossl_event_get_type>, B<ossl_event_get_priority> and 172B<ossl_event_get_when> return the corresponding event field. 173 174B<ossl_event_get0_payload> returns a pointer to the event's payload. 175 176B<ossl_event_queue_add>, B<ossl_event_queue_remove>, 177B<ossl_event_queue_postpone_until> and 178B<ossl_event_queue_get1_next_event> return 1 on success and 0 on failure. 179 180B<ossl_event_time_until> and B<ossl_event_queue_time_until_next> 181return a time until the next event or B<OSSL_TIME_INFINITY> if there is no 182next event. 183 184=head1 SEE ALSO 185 186L<OSSL_TIME(3)> 187 188=head1 HISTORY 189 190This functionality was added to OpenSSL 3.2. 191 192=head1 COPYRIGHT 193 194Copyright 2022-2023 The OpenSSL Project Authors. All Rights Reserved. 195 196Licensed under the Apache License 2.0 (the "License"). You may not use this 197file except in compliance with the License. You can obtain a copy in the file 198LICENSE in the source distribution or at 199L<https://www.openssl.org/source/license.html>. 200 201=cut 202