{"id":2201,"date":"2014-02-24T13:00:13","date_gmt":"2014-02-24T13:00:13","guid":{"rendered":"http:\/\/writeasync.net\/?p=2201"},"modified":"2014-02-23T23:59:00","modified_gmt":"2014-02-23T23:59:00","slug":"overlapped-io","status":"publish","type":"post","link":"http:\/\/writeasync.net\/?p=2201","title":{"rendered":"Introducing overlapped I\/O"},"content":{"rendered":"

In Windows, I\/O operations such as ReadFile<\/code><\/a> can be performed synchronously or asynchronously. Asynchronous I\/O is generally referred to as overlapped I\/O<\/a> since multiple operations can be issued at once and “overlap” in their request lifetimes. There are a few techniques for dealing with overlapped I\/O, but they basically boil down to using either alertable I\/O<\/a> or I\/O completion ports<\/a>.<\/p>\n

Alertable I\/O relies on asynchronous procedure calls<\/a> and is more limited — in particular, the completion callback always runs on the same thread as the original request and cannot be dispatched until the thread is in “alertable state” (which generally involves calling a blocking wait function like WaitForSingleObjectEx<\/code><\/a>). This really isn’t compatible with the continuation-passing style<\/a> of asynchronous programming which is implemented by the Parallel Patterns Library<\/a> in C++ and the Task Parallel Library<\/a> in .NET.<\/p>\n

So that leaves I\/O completion ports as the mechanism of choice for native async, and indeed this is the mechanism used under the hood by .NET APIs like FileStream.ReadAsync<\/code><\/a> (assuming of course that FileStream.IsAsync<\/code><\/a> is true<\/code>). Unfortunately, direct manipulation of completion ports is rather complicated (although Kenny Kerr<\/a>‘s illuminating blog post “I\/O Completion Ports”<\/a> helps a bit). Luckily there is a (relatively) simpler way with the new thread pool API<\/a> available since Windows Vista. Using CreateThreadPoolIo<\/code><\/a>, StartThreadPoolIo<\/code><\/a>, etc. an application can use worker threads in the thread pool to efficiently handle I\/O completion callbacks.<\/p>\n

Let’s walk through an example set of C++ classes for handling asynchronous file reading. (I should note that in the middle of writing this example I saw Artur Laksberg’s blog post “Simplifying Overlapped I\/O With PPL”<\/a> which covers very similar ground, though there is hopefully enough “value-add” in this post to justify its existence.) First, a few core includes, namespaces, and classes:<\/p>\n

\r\n#include <Windows.h>\r\n#include <string>\r\n#include <iostream>\r\n#include <sstream>\r\n#include <vector>\r\n#include <stdexcept>\r\n#include <memory>\r\n#include <functional>\r\n#include <ppltasks.h>\r\n#include "ppltasks_extra.h"\r\n\r\nusing namespace concurrency;\r\nusing namespace concurrency::extras;\r\nusing namespace std;\r\n\r\n\/\/ Utility function to trace a message with a thread ID\r\nvoid TraceThread(wstring const & text)\r\n{\r\n    DWORD id = GetCurrentThreadId();\r\n    wstringstream wss;\r\n    wss << L"[T=" << id << L"] " << text << endl;\r\n    wcout << wss.str();\r\n}\r\n\r\n\/\/ Base class to mark a class as non-copyable\r\nstruct DenyCopy\r\n{\r\n    DenyCopy() { }\r\n    ~DenyCopy() { }\r\n    DenyCopy & operator =(DenyCopy const &) = delete;\r\n    DenyCopy(DenyCopy const &) = delete;\r\n};\r\n\r\n\/\/ Exception created from generic Win32 error code.\r\nclass Win32Error : public runtime_error\r\n{\r\npublic:\r\n    Win32Error(string const & message, DWORD error)\r\n        : runtime_error(message),\r\n        error_(error)\r\n    {\r\n    }\r\n\r\n    ~Win32Error() { }\r\n\r\n    DWORD get_Error() const { return error_; }\r\n\r\nprivate:\r\n    DWORD error_;\r\n};\r\n\r\n\/\/ IO-specific exception associated with a given file.\r\nclass IOError : public Win32Error\r\n{\r\npublic:\r\n    IOError(string const & message, DWORD error, wstring const & fileName)\r\n        : Win32Error(message, error),\r\n        fileName_(fileName)\r\n    {\r\n    }\r\n\r\n    ~IOError() { }\r\n\r\n    wstring const & get_FileName() const { return fileName_; }\r\n\r\nprivate:\r\n    wstring fileName_;\r\n};\r\n<\/pre>\n
Now, we need a file handle wrapper that will open a file for reading and prepare it for overlapped I\/O. We’ll need use CreateFile<\/code><\/a> (with OPEN_EXISTING<\/code>) and pass FILE_FLAG_OVERLAPPED<\/code><\/a> otherwise all async I\/O attempts will fail:<\/p>\n
\r\nclass FileReadHandle : private DenyCopy\r\n{\r\npublic:\r\n    FileReadHandle(wstring const & fileName)\r\n        : fileName_(fileName),\r\n        handle_(CreateFile(fileName.c_str(), GENERIC_READ, FILE_SHARE_READ, nullptr, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL | FILE_FLAG_OVERLAPPED, nullptr))\r\n    {\r\n        if (handle_ == INVALID_HANDLE_VALUE)\r\n        {\r\n            DWORD error = GetLastError();\r\n            throw IOError("Open failed.", error, fileName);\r\n        }\r\n    }\r\n\r\n    ~FileReadHandle()\r\n    {\r\n        CloseHandle(handle_);\r\n    }\r\n\r\n    wstring const & get_FileName() const { return fileName_; }\r\n\r\n    HANDLE get_Value() { return handle_; }\r\n\r\nprivate:\r\n    wstring fileName_;\r\n    HANDLE handle_;\r\n};\r\n<\/pre>\n
Now we need to add some code for manipulating I\/O worker threads. The expected workflow involves multiple steps as follows:<\/p>\n