Windows File System Async API Reference

Asynchronous File Operations (I/O)

This section covers the asynchronous programming model for interacting with the Windows file system. Asynchronous I/O allows your application to initiate an operation and continue executing without waiting for the operation to complete, significantly improving responsiveness and resource utilization.

Overview of Asynchronous I/O

Windows provides several mechanisms for asynchronous file operations. The most common involve:

• Overlapped I/O: The fundamental Win32 API for asynchronous operations.
• I/O Completion Ports (IOCP): A highly scalable mechanism for managing asynchronous I/O completion notifications.
• ReadDirectoryChangesW: For monitoring directory changes asynchronously.

Core Win32 Functions

CreateFileW with `FILE_FLAG_OVERLAPPED`

To perform asynchronous I/O, you must open the file handle with the FILE_FLAG_OVERLAPPED flag:

Key parameters when using FILE_FLAG_OVERLAPPED:

• dwFlagsAndAttributes must include FILE_FLAG_OVERLAPPED.
• dwFlagsAndAttributes can also include FILE_FLAG_NO_BUFFERING for direct disk access, which can sometimes improve performance for large I/O operations but requires careful alignment.

OVERLAPPED Structure

The OVERLAPPED structure is central to managing asynchronous operations. It holds information about the pending I/O request, including an event handle that can be signaled upon completion.

• hEvent: A handle to an event object. This event is signaled when the I/O operation is complete. If this member is NULL, the system uses the event handle within the structure for the overlapped I/O object. It's common to create an event using CreateEventW.

Reading and Writing Asynchronously

Use ReadFile and WriteFile with a populated OVERLAPPED structure for asynchronous operations.

ReadFile

• If the function returns FALSE, call GetLastError. If the error is ERROR_IO_PENDING, the operation is in progress and will complete asynchronously. The actual number of bytes read will be in lpNumberOfBytesRead when the operation completes.

WriteFile

• Similar to ReadFile, if it returns FALSE and GetLastError is ERROR_IO_PENDING, the write operation is asynchronous.

Checking for Completion

There are several ways to check if an asynchronous I/O operation has completed:

1. Polling the Event Handle: Use WaitForSingleObject or WaitForMultipleObjects on the OVERLAPPED.hEvent.
2. Using GetOverlappedResult: This function can wait for the operation to complete or retrieve the status of a pending operation.

GetOverlappedResult

• bWait: If TRUE, the function waits for the operation to complete. If FALSE, it immediately returns the status.

I/O Completion Ports (IOCP)

For high-performance servers or applications handling many concurrent I/O operations, I/O Completion Ports are the preferred mechanism. They provide a thread-pool management system that efficiently handles I/O completions.

• CreateIoCompletionPort
• PostQueuedCompletionStatus
• GetQueuedCompletionStatus

Using IOCP typically involves creating a single completion port, associating file handles with it, and then having multiple worker threads call GetQueuedCompletionStatus to process completed I/O operations.

Monitoring Directory Changes

The ReadDirectoryChangesW function allows you to monitor a directory for changes (creation, deletion, renaming of files).

• This function is inherently asynchronous. You must provide an OVERLAPPED structure and optionally a completion routine.
• dwNotifyFilter specifies the types of changes to monitor (e.g., FILE_NOTIFY_CHANGE_FILE_NAME, FILE_NOTIFY_CHANGE_DIR_NAME, FILE_NOTIFY_CHANGE_LAST_WRITE).