jpayne@69: // Copyright (c) 2016 Sandstorm Development Group, Inc. and contributors jpayne@69: // Licensed under the MIT License: jpayne@69: // jpayne@69: // Permission is hereby granted, free of charge, to any person obtaining a copy jpayne@69: // of this software and associated documentation files (the "Software"), to deal jpayne@69: // in the Software without restriction, including without limitation the rights jpayne@69: // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell jpayne@69: // copies of the Software, and to permit persons to whom the Software is jpayne@69: // furnished to do so, subject to the following conditions: jpayne@69: // jpayne@69: // The above copyright notice and this permission notice shall be included in jpayne@69: // all copies or substantial portions of the Software. jpayne@69: // jpayne@69: // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR jpayne@69: // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, jpayne@69: // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE jpayne@69: // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER jpayne@69: // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, jpayne@69: // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN jpayne@69: // THE SOFTWARE. jpayne@69: jpayne@69: #pragma once jpayne@69: jpayne@69: #if !_WIN32 jpayne@69: #error "This file is Windows-specific. On Unix, include async-unix.h instead." jpayne@69: #endif jpayne@69: jpayne@69: // Include windows.h as lean as possible. (If you need more of the Windows API for your app, jpayne@69: // #include windows.h yourself before including this header.) jpayne@69: #include jpayne@69: jpayne@69: #include "async.h" jpayne@69: #include "timer.h" jpayne@69: #include "io.h" jpayne@69: #include jpayne@69: #include jpayne@69: jpayne@69: #include jpayne@69: #include jpayne@69: jpayne@69: KJ_BEGIN_HEADER jpayne@69: jpayne@69: namespace kj { jpayne@69: jpayne@69: class Win32EventPort: public EventPort { jpayne@69: // Abstract base interface for EventPorts that can listen on Win32 event types. Due to the jpayne@69: // absurd complexity of the Win32 API, it's not possible to standardize on a single jpayne@69: // implementation of EventPort. In particular, there is no way for a single thread to use I/O jpayne@69: // completion ports (the most efficient way of handling I/O) while at the same time waiting for jpayne@69: // signalable handles or UI messages. jpayne@69: // jpayne@69: // Note that UI messages are not supported at all by this interface because the message queue jpayne@69: // is implemented by user32.dll and we want libkj to depend only on kernel32.dll. A separate jpayne@69: // compat library could provide a Win32EventPort implementation that works with the UI message jpayne@69: // queue. jpayne@69: jpayne@69: public: jpayne@69: // --------------------------------------------------------------------------- jpayne@69: // overlapped I/O jpayne@69: jpayne@69: struct IoResult { jpayne@69: DWORD errorCode; jpayne@69: DWORD bytesTransferred; jpayne@69: }; jpayne@69: jpayne@69: class IoOperation { jpayne@69: public: jpayne@69: virtual LPOVERLAPPED getOverlapped() = 0; jpayne@69: // Gets the OVERLAPPED structure to pass to the Win32 I/O call. Do NOT modify it; just pass it jpayne@69: // on. jpayne@69: jpayne@69: virtual Promise onComplete() = 0; jpayne@69: // After making the Win32 call, if the return value indicates that the operation was jpayne@69: // successfully queued (i.e. the completion event will definitely occur), call this to wait jpayne@69: // for completion. jpayne@69: // jpayne@69: // You MUST call this if the operation was successfully queued, and you MUST NOT call this jpayne@69: // otherwise. If the Win32 call failed (without queuing any operation or event) then you should jpayne@69: // simply drop the IoOperation object. jpayne@69: // jpayne@69: // Dropping the returned Promise cancels the operation via Win32's CancelIoEx(). The destructor jpayne@69: // will wait for the cancellation to complete, such that after dropping the proimse it is safe jpayne@69: // to free the buffer that the operation was reading from / writing to. jpayne@69: // jpayne@69: // You may safely drop the `IoOperation` while still waiting for this promise. You may not, jpayne@69: // however, drop the `IoObserver`. jpayne@69: }; jpayne@69: jpayne@69: class IoObserver { jpayne@69: public: jpayne@69: virtual Own newOperation(uint64_t offset) = 0; jpayne@69: // Begin an I/O operation. For file operations, `offset` is the offset within the file at jpayne@69: // which the operation will start. For stream operations, `offset` is ignored. jpayne@69: }; jpayne@69: jpayne@69: virtual Own observeIo(HANDLE handle) = 0; jpayne@69: // Given a handle which supports overlapped I/O, arrange to receive I/O completion events via jpayne@69: // this EventPort. jpayne@69: // jpayne@69: // Different Win32EventPort implementations may handle this in different ways, such as by using jpayne@69: // completion routines (APCs) or by using I/O completion ports. The caller should not assume jpayne@69: // any particular technique. jpayne@69: // jpayne@69: // WARNING: It is only safe to call observeIo() on a particular handle once during its lifetime. jpayne@69: // You cannot observe the same handle from multiple Win32EventPorts, even if not at the same jpayne@69: // time. This is because the Win32 API provides no way to disassociate a handle from an I/O jpayne@69: // completion port once it is associated. jpayne@69: jpayne@69: // --------------------------------------------------------------------------- jpayne@69: // signalable handles jpayne@69: // jpayne@69: // Warning: Due to limitations in the Win32 API, implementations of EventPort may be forced to jpayne@69: // spawn additional threads to wait for signaled objects. This is necessary if the EventPort jpayne@69: // implementation is based on I/O completion ports, or if you need to wait on more than 64 jpayne@69: // handles at once. jpayne@69: jpayne@69: class SignalObserver { jpayne@69: public: jpayne@69: virtual Promise onSignaled() = 0; jpayne@69: // Returns a promise that completes the next time the handle enters the signaled state. jpayne@69: // jpayne@69: // Depending on the type of handle, the handle may automatically be reset to a non-signaled jpayne@69: // state before the promise resolves. The underlying implementation uses WaitForSingleObject() jpayne@69: // or an equivalent wait call, so check the documentation for that to understand the semantics. jpayne@69: // jpayne@69: // If the handle is a mutex and it is abandoned without being unlocked, the promise breaks with jpayne@69: // an exception. jpayne@69: jpayne@69: virtual Promise onSignaledOrAbandoned() = 0; jpayne@69: // Like onSignaled(), but instead of throwing when a mutex is abandoned, resolves to `true`. jpayne@69: // Resolves to `false` for non-abandoned signals. jpayne@69: }; jpayne@69: jpayne@69: virtual Own observeSignalState(HANDLE handle) = 0; jpayne@69: // Given a handle that supports waiting for it to become "signaled" via WaitForSingleObject(), jpayne@69: // return an object that can wait for this state using the EventPort. jpayne@69: jpayne@69: // --------------------------------------------------------------------------- jpayne@69: // APCs jpayne@69: jpayne@69: virtual void allowApc() = 0; jpayne@69: // If this is ever called, the Win32EventPort will switch modes so that APCs can be scheduled jpayne@69: // on the thread, e.g. through the Win32 QueueUserAPC() call. In the future, this may be enabled jpayne@69: // by default. However, as of this writing, Wine does not support the necessary jpayne@69: // GetQueuedCompletionStatusEx() call, thus allowApc() breaks Wine support. (Tested on Wine jpayne@69: // 1.8.7.) jpayne@69: // jpayne@69: // If the event port implementation can't support APCs for some reason, this throws. jpayne@69: jpayne@69: // --------------------------------------------------------------------------- jpayne@69: // time jpayne@69: jpayne@69: virtual Timer& getTimer() = 0; jpayne@69: }; jpayne@69: jpayne@69: class Win32WaitObjectThreadPool { jpayne@69: // Helper class that implements Win32EventPort::observeSignalState() by spawning additional jpayne@69: // threads as needed to perform the actual waiting. jpayne@69: // jpayne@69: // This class is intended to be used to assist in building Win32EventPort implementations. jpayne@69: jpayne@69: public: jpayne@69: Win32WaitObjectThreadPool(uint mainThreadCount = 0); jpayne@69: // `mainThreadCount` indicates the number of objects the main thread is able to listen on jpayne@69: // directly. Typically this would be zero (e.g. if the main thread watches an I/O completion jpayne@69: // port) or MAXIMUM_WAIT_OBJECTS (e.g. if the main thread is a UI thread but can use jpayne@69: // MsgWaitForMultipleObjectsEx() to wait on some handles at the same time as messages). jpayne@69: jpayne@69: Own observeSignalState(HANDLE handle); jpayne@69: // Implemetns Win32EventPort::observeSignalState(). jpayne@69: jpayne@69: uint prepareMainThreadWait(HANDLE* handles[]); jpayne@69: // Call immediately before invoking WaitForMultipleObjects() or similar in the main thread. jpayne@69: // Fills in `handles` with the handle pointers to wait on, and returns the number of handles jpayne@69: // in this array. (The array should be allocated to be at least the size passed to the jpayne@69: // constructor). jpayne@69: // jpayne@69: // There's no need to call this if `mainThreadCount` as passed to the constructor was zero. jpayne@69: jpayne@69: bool finishedMainThreadWait(DWORD returnCode); jpayne@69: // Call immediately after invoking WaitForMultipleObjects() or similar in the main thread, jpayne@69: // passing the value returned by that call. Returns true if the event indicated by `returnCode` jpayne@69: // has been handled (i.e. it was WAIT_OBJECT_n or WAIT_ABANDONED_n where n is in-range for the jpayne@69: // last call to prepareMainThreadWait()). jpayne@69: }; jpayne@69: jpayne@69: class Win32IocpEventPort final: public Win32EventPort { jpayne@69: // An EventPort implementation which uses Windows I/O completion ports to listen for events. jpayne@69: // jpayne@69: // With this implementation, observeSignalState() requires spawning a separate thread. jpayne@69: jpayne@69: public: jpayne@69: Win32IocpEventPort(); jpayne@69: ~Win32IocpEventPort() noexcept(false); jpayne@69: jpayne@69: // implements EventPort ------------------------------------------------------ jpayne@69: bool wait() override; jpayne@69: bool poll() override; jpayne@69: void wake() const override; jpayne@69: jpayne@69: // implements Win32IocpEventPort --------------------------------------------- jpayne@69: Own observeIo(HANDLE handle) override; jpayne@69: Own observeSignalState(HANDLE handle) override; jpayne@69: Timer& getTimer() override { return timerImpl; } jpayne@69: void allowApc() override { isAllowApc = true; } jpayne@69: jpayne@69: private: jpayne@69: class IoPromiseAdapter; jpayne@69: class IoOperationImpl; jpayne@69: class IoObserverImpl; jpayne@69: jpayne@69: const MonotonicClock& clock; jpayne@69: jpayne@69: AutoCloseHandle iocp; jpayne@69: AutoCloseHandle thread; jpayne@69: Win32WaitObjectThreadPool waitThreads; jpayne@69: TimerImpl timerImpl; jpayne@69: mutable std::atomic sentWake {false}; jpayne@69: bool isAllowApc = false; jpayne@69: jpayne@69: void waitIocp(DWORD timeoutMs); jpayne@69: // Wait on the I/O completion port for up to timeoutMs and pump events. Does not advance the jpayne@69: // timer; caller must do that. jpayne@69: jpayne@69: bool receivedWake(); jpayne@69: jpayne@69: static AutoCloseHandle newIocpHandle(); jpayne@69: static AutoCloseHandle openCurrentThread(); jpayne@69: }; jpayne@69: jpayne@69: } // namespace kj jpayne@69: jpayne@69: KJ_END_HEADER