]>
Commit | Line | Data |
---|---|---|
e6be47e4 P |
1 | /* |
2 | * Copyright 2022 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 | * | |
eb4129e1 | 103 | * The function returns NULL on failure and the added event on success. |
e6be47e4 P |
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 | * | |
eb4129e1 | 116 | * The function returns 0 on failure and 1 on success. |
e6be47e4 P |
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 |