Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/kj/async-win32.h @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
rev   line source
jpayne@69 1 // Copyright (c) 2016 Sandstorm Development Group, Inc. and contributors
jpayne@69 2 // Licensed under the MIT License:
jpayne@69 3 //
jpayne@69 4 // Permission is hereby granted, free of charge, to any person obtaining a copy
jpayne@69 5 // of this software and associated documentation files (the "Software"), to deal
jpayne@69 6 // in the Software without restriction, including without limitation the rights
jpayne@69 7 // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
jpayne@69 8 // copies of the Software, and to permit persons to whom the Software is
jpayne@69 9 // furnished to do so, subject to the following conditions:
jpayne@69 10 //
jpayne@69 11 // The above copyright notice and this permission notice shall be included in
jpayne@69 12 // all copies or substantial portions of the Software.
jpayne@69 13 //
jpayne@69 14 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
jpayne@69 15 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
jpayne@69 16 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
jpayne@69 17 // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
jpayne@69 18 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
jpayne@69 19 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
jpayne@69 20 // THE SOFTWARE.
jpayne@69 21
jpayne@69 22 #pragma once
jpayne@69 23
jpayne@69 24 #if !_WIN32
jpayne@69 25 #error "This file is Windows-specific. On Unix, include async-unix.h instead."
jpayne@69 26 #endif
jpayne@69 27
jpayne@69 28 // Include windows.h as lean as possible. (If you need more of the Windows API for your app,
jpayne@69 29 // #include windows.h yourself before including this header.)
jpayne@69 30 #include <kj/win32-api-version.h>
jpayne@69 31
jpayne@69 32 #include "async.h"
jpayne@69 33 #include "timer.h"
jpayne@69 34 #include "io.h"
jpayne@69 35 #include <atomic>
jpayne@69 36 #include <inttypes.h>
jpayne@69 37
jpayne@69 38 #include <windows.h>
jpayne@69 39 #include <kj/windows-sanity.h>
jpayne@69 40
jpayne@69 41 KJ_BEGIN_HEADER
jpayne@69 42
jpayne@69 43 namespace kj {
jpayne@69 44
jpayne@69 45 class Win32EventPort: public EventPort {
jpayne@69 46 // Abstract base interface for EventPorts that can listen on Win32 event types. Due to the
jpayne@69 47 // absurd complexity of the Win32 API, it's not possible to standardize on a single
jpayne@69 48 // implementation of EventPort. In particular, there is no way for a single thread to use I/O
jpayne@69 49 // completion ports (the most efficient way of handling I/O) while at the same time waiting for
jpayne@69 50 // signalable handles or UI messages.
jpayne@69 51 //
jpayne@69 52 // Note that UI messages are not supported at all by this interface because the message queue
jpayne@69 53 // is implemented by user32.dll and we want libkj to depend only on kernel32.dll. A separate
jpayne@69 54 // compat library could provide a Win32EventPort implementation that works with the UI message
jpayne@69 55 // queue.
jpayne@69 56
jpayne@69 57 public:
jpayne@69 58 // ---------------------------------------------------------------------------
jpayne@69 59 // overlapped I/O
jpayne@69 60
jpayne@69 61 struct IoResult {
jpayne@69 62 DWORD errorCode;
jpayne@69 63 DWORD bytesTransferred;
jpayne@69 64 };
jpayne@69 65
jpayne@69 66 class IoOperation {
jpayne@69 67 public:
jpayne@69 68 virtual LPOVERLAPPED getOverlapped() = 0;
jpayne@69 69 // Gets the OVERLAPPED structure to pass to the Win32 I/O call. Do NOT modify it; just pass it
jpayne@69 70 // on.
jpayne@69 71
jpayne@69 72 virtual Promise<IoResult> onComplete() = 0;
jpayne@69 73 // After making the Win32 call, if the return value indicates that the operation was
jpayne@69 74 // successfully queued (i.e. the completion event will definitely occur), call this to wait
jpayne@69 75 // for completion.
jpayne@69 76 //
jpayne@69 77 // You MUST call this if the operation was successfully queued, and you MUST NOT call this
jpayne@69 78 // otherwise. If the Win32 call failed (without queuing any operation or event) then you should
jpayne@69 79 // simply drop the IoOperation object.
jpayne@69 80 //
jpayne@69 81 // Dropping the returned Promise cancels the operation via Win32's CancelIoEx(). The destructor
jpayne@69 82 // will wait for the cancellation to complete, such that after dropping the proimse it is safe
jpayne@69 83 // to free the buffer that the operation was reading from / writing to.
jpayne@69 84 //
jpayne@69 85 // You may safely drop the `IoOperation` while still waiting for this promise. You may not,
jpayne@69 86 // however, drop the `IoObserver`.
jpayne@69 87 };
jpayne@69 88
jpayne@69 89 class IoObserver {
jpayne@69 90 public:
jpayne@69 91 virtual Own<IoOperation> newOperation(uint64_t offset) = 0;
jpayne@69 92 // Begin an I/O operation. For file operations, `offset` is the offset within the file at
jpayne@69 93 // which the operation will start. For stream operations, `offset` is ignored.
jpayne@69 94 };
jpayne@69 95
jpayne@69 96 virtual Own<IoObserver> observeIo(HANDLE handle) = 0;
jpayne@69 97 // Given a handle which supports overlapped I/O, arrange to receive I/O completion events via
jpayne@69 98 // this EventPort.
jpayne@69 99 //
jpayne@69 100 // Different Win32EventPort implementations may handle this in different ways, such as by using
jpayne@69 101 // completion routines (APCs) or by using I/O completion ports. The caller should not assume
jpayne@69 102 // any particular technique.
jpayne@69 103 //
jpayne@69 104 // WARNING: It is only safe to call observeIo() on a particular handle once during its lifetime.
jpayne@69 105 // You cannot observe the same handle from multiple Win32EventPorts, even if not at the same
jpayne@69 106 // time. This is because the Win32 API provides no way to disassociate a handle from an I/O
jpayne@69 107 // completion port once it is associated.
jpayne@69 108
jpayne@69 109 // ---------------------------------------------------------------------------
jpayne@69 110 // signalable handles
jpayne@69 111 //
jpayne@69 112 // Warning: Due to limitations in the Win32 API, implementations of EventPort may be forced to
jpayne@69 113 // spawn additional threads to wait for signaled objects. This is necessary if the EventPort
jpayne@69 114 // implementation is based on I/O completion ports, or if you need to wait on more than 64
jpayne@69 115 // handles at once.
jpayne@69 116
jpayne@69 117 class SignalObserver {
jpayne@69 118 public:
jpayne@69 119 virtual Promise<void> onSignaled() = 0;
jpayne@69 120 // Returns a promise that completes the next time the handle enters the signaled state.
jpayne@69 121 //
jpayne@69 122 // Depending on the type of handle, the handle may automatically be reset to a non-signaled
jpayne@69 123 // state before the promise resolves. The underlying implementation uses WaitForSingleObject()
jpayne@69 124 // or an equivalent wait call, so check the documentation for that to understand the semantics.
jpayne@69 125 //
jpayne@69 126 // If the handle is a mutex and it is abandoned without being unlocked, the promise breaks with
jpayne@69 127 // an exception.
jpayne@69 128
jpayne@69 129 virtual Promise<bool> onSignaledOrAbandoned() = 0;
jpayne@69 130 // Like onSignaled(), but instead of throwing when a mutex is abandoned, resolves to `true`.
jpayne@69 131 // Resolves to `false` for non-abandoned signals.
jpayne@69 132 };
jpayne@69 133
jpayne@69 134 virtual Own<SignalObserver> observeSignalState(HANDLE handle) = 0;
jpayne@69 135 // Given a handle that supports waiting for it to become "signaled" via WaitForSingleObject(),
jpayne@69 136 // return an object that can wait for this state using the EventPort.
jpayne@69 137
jpayne@69 138 // ---------------------------------------------------------------------------
jpayne@69 139 // APCs
jpayne@69 140
jpayne@69 141 virtual void allowApc() = 0;
jpayne@69 142 // If this is ever called, the Win32EventPort will switch modes so that APCs can be scheduled
jpayne@69 143 // on the thread, e.g. through the Win32 QueueUserAPC() call. In the future, this may be enabled
jpayne@69 144 // by default. However, as of this writing, Wine does not support the necessary
jpayne@69 145 // GetQueuedCompletionStatusEx() call, thus allowApc() breaks Wine support. (Tested on Wine
jpayne@69 146 // 1.8.7.)
jpayne@69 147 //
jpayne@69 148 // If the event port implementation can't support APCs for some reason, this throws.
jpayne@69 149
jpayne@69 150 // ---------------------------------------------------------------------------
jpayne@69 151 // time
jpayne@69 152
jpayne@69 153 virtual Timer& getTimer() = 0;
jpayne@69 154 };
jpayne@69 155
jpayne@69 156 class Win32WaitObjectThreadPool {
jpayne@69 157 // Helper class that implements Win32EventPort::observeSignalState() by spawning additional
jpayne@69 158 // threads as needed to perform the actual waiting.
jpayne@69 159 //
jpayne@69 160 // This class is intended to be used to assist in building Win32EventPort implementations.
jpayne@69 161
jpayne@69 162 public:
jpayne@69 163 Win32WaitObjectThreadPool(uint mainThreadCount = 0);
jpayne@69 164 // `mainThreadCount` indicates the number of objects the main thread is able to listen on
jpayne@69 165 // directly. Typically this would be zero (e.g. if the main thread watches an I/O completion
jpayne@69 166 // port) or MAXIMUM_WAIT_OBJECTS (e.g. if the main thread is a UI thread but can use
jpayne@69 167 // MsgWaitForMultipleObjectsEx() to wait on some handles at the same time as messages).
jpayne@69 168
jpayne@69 169 Own<Win32EventPort::SignalObserver> observeSignalState(HANDLE handle);
jpayne@69 170 // Implemetns Win32EventPort::observeSignalState().
jpayne@69 171
jpayne@69 172 uint prepareMainThreadWait(HANDLE* handles[]);
jpayne@69 173 // Call immediately before invoking WaitForMultipleObjects() or similar in the main thread.
jpayne@69 174 // Fills in `handles` with the handle pointers to wait on, and returns the number of handles
jpayne@69 175 // in this array. (The array should be allocated to be at least the size passed to the
jpayne@69 176 // constructor).
jpayne@69 177 //
jpayne@69 178 // There's no need to call this if `mainThreadCount` as passed to the constructor was zero.
jpayne@69 179
jpayne@69 180 bool finishedMainThreadWait(DWORD returnCode);
jpayne@69 181 // Call immediately after invoking WaitForMultipleObjects() or similar in the main thread,
jpayne@69 182 // passing the value returned by that call. Returns true if the event indicated by `returnCode`
jpayne@69 183 // has been handled (i.e. it was WAIT_OBJECT_n or WAIT_ABANDONED_n where n is in-range for the
jpayne@69 184 // last call to prepareMainThreadWait()).
jpayne@69 185 };
jpayne@69 186
jpayne@69 187 class Win32IocpEventPort final: public Win32EventPort {
jpayne@69 188 // An EventPort implementation which uses Windows I/O completion ports to listen for events.
jpayne@69 189 //
jpayne@69 190 // With this implementation, observeSignalState() requires spawning a separate thread.
jpayne@69 191
jpayne@69 192 public:
jpayne@69 193 Win32IocpEventPort();
jpayne@69 194 ~Win32IocpEventPort() noexcept(false);
jpayne@69 195
jpayne@69 196 // implements EventPort ------------------------------------------------------
jpayne@69 197 bool wait() override;
jpayne@69 198 bool poll() override;
jpayne@69 199 void wake() const override;
jpayne@69 200
jpayne@69 201 // implements Win32IocpEventPort ---------------------------------------------
jpayne@69 202 Own<IoObserver> observeIo(HANDLE handle) override;
jpayne@69 203 Own<SignalObserver> observeSignalState(HANDLE handle) override;
jpayne@69 204 Timer& getTimer() override { return timerImpl; }
jpayne@69 205 void allowApc() override { isAllowApc = true; }
jpayne@69 206
jpayne@69 207 private:
jpayne@69 208 class IoPromiseAdapter;
jpayne@69 209 class IoOperationImpl;
jpayne@69 210 class IoObserverImpl;
jpayne@69 211
jpayne@69 212 const MonotonicClock& clock;
jpayne@69 213
jpayne@69 214 AutoCloseHandle iocp;
jpayne@69 215 AutoCloseHandle thread;
jpayne@69 216 Win32WaitObjectThreadPool waitThreads;
jpayne@69 217 TimerImpl timerImpl;
jpayne@69 218 mutable std::atomic<bool> sentWake {false};
jpayne@69 219 bool isAllowApc = false;
jpayne@69 220
jpayne@69 221 void waitIocp(DWORD timeoutMs);
jpayne@69 222 // Wait on the I/O completion port for up to timeoutMs and pump events. Does not advance the
jpayne@69 223 // timer; caller must do that.
jpayne@69 224
jpayne@69 225 bool receivedWake();
jpayne@69 226
jpayne@69 227 static AutoCloseHandle newIocpHandle();
jpayne@69 228 static AutoCloseHandle openCurrentThread();
jpayne@69 229 };
jpayne@69 230
jpayne@69 231 } // namespace kj
jpayne@69 232
jpayne@69 233 KJ_END_HEADER