doc/internal/man3/OSSL_EVENT.pod

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