include/internal/event_queue.h

   1 /*
   2  * Copyright 2022-2023 The OpenSSL Project Authors. All Rights Reserved.
   3  *
   4  * Licensed under the Apache License 2.0 (the "License").  You may not use
   5  * this file except in compliance with the License.  You can obtain a copy
   6  * in the file LICENSE in the source distribution or at
   7  * https://www.openssl.org/source/license.html
   8  */
   9
  10 #ifndef OSSL_INTERNAL_EVENT_QUEUE_H
  11 # define OSSL_INTERNAL_EVENT_QUEUE_H
  12 # pragma once
  13
  14 # include "internal/priority_queue.h"
  15 # include "internal/time.h"
  16
  17 /*
  18  * Opaque type holding an event.
  19  */
  20 typedef struct ossl_event_st OSSL_EVENT;
  21
  22 DEFINE_PRIORITY_QUEUE_OF(OSSL_EVENT);
  23
  24 /*
  25  * Public type representing an event queue, the underlying structure being
  26  * opaque.
  27  */
  28 typedef struct ossl_event_queue_st OSSL_EVENT_QUEUE;
  29
  30 /*
  31  * Public type representing a event queue entry.
  32  * It is (internally) public so that it can be embedded into other structures,
  33  * it should otherwise be treated as opaque.
  34  */
  35 struct ossl_event_st {
  36     uint32_t type;              /* What type of event this is               */
  37     uint32_t priority;          /* What priority this event has             */
  38     OSSL_TIME when;             /* When the event is scheduled to happen    */
  39     void *ctx;                  /* User argument passed to call backs       */
  40     void *payload;              /* Event specific data of unknown kind      */
  41     size_t payload_size;        /* Length (in bytes) of event specific data */
  42
  43     /* These fields are for internal use only */
  44     PRIORITY_QUEUE_OF(OSSL_EVENT) *queue;    /* Queue containing this event */
  45     size_t ref;                 /* ID for this event                        */
  46     unsigned int flag_dynamic : 1;  /* Malloced or not?                     */
  47 };
  48
  49 /*
  50  * Utility function to populate an event structure and add it to the queue
  51  */
  52 int ossl_event_queue_add(OSSL_EVENT_QUEUE *queue, OSSL_EVENT *event,
  53                          uint32_t type, uint32_t priority,
  54                          OSSL_TIME when, void *ctx,
  55                          void *payload, size_t payload_size);
  56
  57 /*
  58  * Utility functions to extract event fields
  59  */
  60 static ossl_unused ossl_inline
  61 uint32_t ossl_event_get_type(const OSSL_EVENT *event)
  62 {
  63     return event->type;
  64 }
  65
  66 static ossl_unused ossl_inline
  67 uint32_t ossl_event_get_priority(const OSSL_EVENT *event)
  68 {
  69     return event->priority;
  70 }
  71
  72 static ossl_unused ossl_inline
  73 OSSL_TIME ossl_event_get_when(const OSSL_EVENT *event)
  74 {
  75     return event->when;
  76 }
  77
  78 static ossl_unused ossl_inline
  79 void *ossl_event_get0_ctx(const OSSL_EVENT *event)
  80 {
  81     return event->ctx;
  82 }
  83
  84 static ossl_unused ossl_inline
  85 void *ossl_event_get0_payload(const OSSL_EVENT *event, size_t *length)
  86 {
  87     if (length != NULL)
  88         *length = event->payload_size;
  89     return event->payload;
  90 }
  91
  92 /*
  93  * Create and free a queue.
  94  */
  95 OSSL_EVENT_QUEUE *ossl_event_queue_new(void);
  96 void ossl_event_queue_free(OSSL_EVENT_QUEUE *queue);
  97
  98 /*
  99  * Schedule a new event into an event queue.
 100  *
 101  * The event parameters are taken from the function arguments.
 102  *
 103  * The function returns NULL on failure and the added event on success.
 104  */
 105 OSSL_EVENT *ossl_event_queue_add_new(OSSL_EVENT_QUEUE *queue,
 106                                      uint32_t type, uint32_t priority,
 107                                      OSSL_TIME when, void *ctx,
 108                                      void *payload, size_t payload_size)
 109 ;
 110
 111 /*
 112  * Schedule an event into an event queue.
 113  *
 114  * The event parameters are taken from the function arguments.
 115  *
 116  * The function returns 0 on failure and 1 on success.
 117  */
 118 int ossl_event_queue_add(OSSL_EVENT_QUEUE *queue, OSSL_EVENT *event,
 119                          uint32_t type, uint32_t priority,
 120                          OSSL_TIME when, void *ctx,
 121                          void *payload, size_t payload_size);
 122
 123 /*
 124  * Delete an event from the queue.
 125  * This will cause the early deletion function to be called if it is non-NULL.
 126  * A pointer to the event structure is returned.
 127  */
 128 int ossl_event_queue_remove(OSSL_EVENT_QUEUE *queue, OSSL_EVENT *event);
 129
 130 /*
 131  * Free a dynamic event.
 132  * Is a NOP for a static event.
 133  */
 134 void ossl_event_free(OSSL_EVENT *event);
 135
 136 /*
 137  * Return the time until the next event for the specified event, if the event's
 138  * time is past, zero is returned.  Once activated, the event reference becomes
 139  * invalid and this function becomes undefined.
 140  */
 141 OSSL_TIME ossl_event_time_until(const OSSL_EVENT *event);
 142
 143 /*
 144  * Return the time until the next event in the queue.
 145  * If the next event is in the past, zero is returned.
 146  */
 147 OSSL_TIME ossl_event_queue_time_until_next(const OSSL_EVENT_QUEUE *queue);
 148
 149 /*
 150  * Postpone an event to trigger at the specified time.
 151  * If the event has triggered, this function's behaviour is undefined.
 152  */
 153 int ossl_event_queue_postpone_until(OSSL_EVENT_QUEUE *queue,
 154                                     OSSL_EVENT *event,
 155                                     OSSL_TIME when);
 156
 157 /*
 158  * Return the next event to process.
 159  */
 160 int ossl_event_queue_get1_next_event(OSSL_EVENT_QUEUE *queue,
 161                                      OSSL_EVENT **event);
 162
 163 #endif