2 * Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.
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
10 #ifndef OSSL_INTERNAL_EVENT_QUEUE_H
11 # define OSSL_INTERNAL_EVENT_QUEUE_H
14 # include "internal/priority_queue.h"
15 # include "internal/time.h"
18 * Opaque type holding an event.
20 typedef struct ossl_event_st OSSL_EVENT;
22 DEFINE_PRIORITY_QUEUE_OF(OSSL_EVENT);
25 * Public type representing an event queue, the underlying structure being
28 typedef struct ossl_event_queue_st OSSL_EVENT_QUEUE;
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.
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 */
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? */
50 * Utility function to populate an event structure and add it to the queue
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);
58 * Utility functions to extract event fields
60 static ossl_unused ossl_inline
61 uint32_t ossl_event_get_type(const OSSL_EVENT *event)
66 static ossl_unused ossl_inline
67 uint32_t ossl_event_get_priority(const OSSL_EVENT *event)
69 return event->priority;
72 static ossl_unused ossl_inline
73 OSSL_TIME ossl_event_get_when(const OSSL_EVENT *event)
78 static ossl_unused ossl_inline
79 void *ossl_event_get0_ctx(const OSSL_EVENT *event)
84 static ossl_unused ossl_inline
85 void *ossl_event_get0_payload(const OSSL_EVENT *event, size_t *length)
88 *length = event->payload_size;
89 return event->payload;
93 * Create and free a queue.
95 OSSL_EVENT_QUEUE *ossl_event_queue_new(void);
96 void ossl_event_queue_free(OSSL_EVENT_QUEUE *queue);
99 * Schedule a new event into an event queue.
101 * The event parameters are taken from the function arguments.
103 * The function returns NULL on failure and the added event on success.
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)
112 * Schedule an event into an event queue.
114 * The event parameters are taken from the function arguments.
116 * The function returns 0 on failure and 1 on success.
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);
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.
128 int ossl_event_queue_remove(OSSL_EVENT_QUEUE *queue, OSSL_EVENT *event);
131 * Free a dynamic event.
132 * Is a NOP for a static event.
134 void ossl_event_free(OSSL_EVENT *event);
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.
141 OSSL_TIME ossl_event_time_until(const OSSL_EVENT *event);
144 * Return the time until the next event in the queue.
145 * If the next event is in the past, zero is returned.
147 OSSL_TIME ossl_event_queue_time_until_next(const OSSL_EVENT_QUEUE *queue);
150 * Postpone an event to trigger at the specified time.
151 * If the event has triggered, this function's behaviour is undefined.
153 int ossl_event_queue_postpone_until(OSSL_EVENT_QUEUE *queue,
158 * Return the next event to process.
160 int ossl_event_queue_get1_next_event(OSSL_EVENT_QUEUE *queue,