1 /* 2 * Copyright 2024-2026 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 #ifndef OSSL_POLL_BUILDER_H 10 #define OSSL_POLL_BUILDER_H 11 12 #include "poll_method.h" 13 #include "internal/time.h" 14 15 /* 16 * RIO_POLL_BUILDER 17 * ================ 18 * 19 * RIO_POLL_BUILDER provides support for immediate-mode polling architectures. 20 * It abstracts OS-specific immediate-mode polling APIs such as select(2) and 21 * poll(2) and allows an arbitrarily large number of FDs to be polled for while 22 * providing minimal overhead (over the OS APIs themselves) for small numbers of 23 * FDs. 24 */ 25 typedef struct rio_poll_builder_st { 26 #if RIO_POLL_METHOD == RIO_POLL_METHOD_NONE 27 int unused_dummy; /* make microsoft compiler happy */ 28 #elif RIO_POLL_METHOD == RIO_POLL_METHOD_SELECT 29 fd_set rfd, wfd, efd; 30 int hwm_fd; 31 #elif RIO_POLL_METHOD == RIO_POLL_METHOD_POLL 32 #define RIO_NUM_STACK_PFDS 32 33 struct pollfd *pfd_heap; 34 struct pollfd pfds[RIO_NUM_STACK_PFDS]; 35 size_t pfd_num, pfd_alloc; 36 #else 37 #error Unknown RIO poll method 38 #endif 39 } RIO_POLL_BUILDER; 40 41 /* 42 * Initialises a new poll builder. 43 * 44 * Returns 1 on success and 0 on failure. 45 */ 46 int ossl_rio_poll_builder_init(RIO_POLL_BUILDER *rpb); 47 48 /* 49 * Tears down a poll builder, freeing any heap allocations (if any) which may 50 * have been made internally. 51 */ 52 void ossl_rio_poll_builder_cleanup(RIO_POLL_BUILDER *rpb); 53 54 /* 55 * Adds a file descriptor to a poll builder. If want_read is 1, listens for 56 * readability events (POLLIN). If want_write is 1, listens for writability 57 * events (POLLOUT). 58 * 59 * If this is called with the same fd twice, the result equivalent to calling 60 * it one time with logically OR'd values of want_read and want_write. 61 * 62 * Returns 1 on success and 0 on failure. 63 */ 64 int ossl_rio_poll_builder_add_fd(RIO_POLL_BUILDER *rpb, int fd, 65 int want_read, int want_write); 66 67 /* 68 * Polls the set of file descriptors added to a poll builder. deadline is a 69 * deadline time based on the ossl_time_now() clock or ossl_time_infinite() for 70 * no timeout. Returns 1 on success or 0 on failure. 71 */ 72 int ossl_rio_poll_builder_poll(RIO_POLL_BUILDER *rpb, OSSL_TIME deadline); 73 74 /* 75 * TODO(RIO): No support currently for readout of what was readable/writeable as 76 * it is currently not needed. 77 */ 78 79 #ifndef OPENSSL_NO_QUIC 80 /* 81 * Test instrumentation only. If set, poll_translate() (see poll_immediate.c) 82 * calls this with the index of each item immediately before translating it, 83 * once all earlier items (if any) have finished translation. This lets 84 * tests inject a readiness change into the gap between translation of 85 * consecutive items, in order to deterministically exercise the 86 * abort-blocking path. Always NULL in production use. 87 */ 88 extern void (*ossl_quic_poll_translate_test_step_cb)(size_t idx, void *arg); 89 extern void *ossl_quic_poll_translate_test_step_cb_arg; 90 #endif 91 92 #endif 93