完成端口(Completion Port)实现思路浅析 [草稿]

 

2009-04-14 18:32

完成端口是 NT 架构下一种高效的异步 IO 辅助机制，其使用方法已经被广为讨论，MSDN里面也有很详细的说明和示例。《Windows网络编程》一书中有关于通过完成端口实现高效网络服务器设计的详细说明；《Windows核心编程》一书中有关于异步IO以及线程池等相关知识的使用介绍；而《Windows 2000 内部揭密 》一书中则有对完成端口实现原理的简要介绍；此外一些关于 Win32 下多线程编程方面的书籍也对完成端口有所提及。
     因此，对于完成端口的使用我这里就不再罗嗦，下面将直接从实现角度对其进行分析。

     首先，从设计角度来看：完成端口是一个 NT 执行子系统的核心对象。通过将完成端口与任意个 I/O 句柄（文件或Socket等）关联，使得用户可以通过完成端口这一统一途径，异步的获取并处理 I/O 操作的结果，同时能够最大限度利用多 CPU 的优势。而且因为完成端口实际上是 NT 系统很多底层机制如 APC 的实现手段，故而在效率上是最高的，因为绝大多数其他类似解决方法最终还是使用完成端口实现。与 WaitForMultipleObjects 函数不同，完成端口是由系统直接提供并行优化支持的，通过建立完成端口时指定的并行线程值，系统可以保证工作在同一完成端口上的线程数量受控（一般等于系统CPU数量），这样就可以避免无意义的线程上下文切换，获取更高的性能。

     其次，从使用角度来看：完成端口使用 CreateIoCompletionPort 函数和 CloseHandle 函数创建和释放，使用 GetQueuedCompletionStatus 函数和 PostQueuedCompletionStatus 函数实现完成端口的读写操作。因此我们的分析从这三个函数开始。

     CreateIoCompletionPort 函数在 ExistingCompletionPort 参数为空的时候调用 NtCreateIoCompletion 函数(iocomplete.c:51)创建一个新的完成端口对象；然后处理 FileHandle 参数为 INVALID_HANDLE_VALUE 时的情况；最后调用 NtSetInformationFile 函数(dll estrfil.c:740)试图将 I/O 句柄绑定到完成端口上。伪代码如下：

以下为引用：

#define IO_COMPLETION_ALL_ACCESS 0x001F0003

typedef enum _FILE_INFORMATION_CLASS
{
   //...
   FileCompletionInformation = 30,
   //...
} FILE_INFORMATION_CLASS, *PFILE_INFORMATION_CLASS;

typedef struct _IO_STATUS_BLOCK
{
   union {
     NTSTATUS Status;
     PVOID Pointer;
   };

   ULONG_PTR Information;
} IO_STATUS_BLOCK, *PIO_STATUS_BLOCK;

HANDLE CreateIoCompletionPort(
   HANDLE FileHandle,
   HANDLE ExistingCompletionPort,
   ULONG_PTR CompletionKey,
   DWORD NumberOfConcurrentThreads)
{
   HANDLE CompletionPort = ExistingCompletionPort;

   // 创建一个新的完成端口对象
   if(ExistingCompletionPort == NULL)
   {
     NTSTATUS st = NtCreateIoCompletion(&CompletionPort, IO_COMPLETION_ALL_ACCESS, NULL, NumberOfConcurrentThreads);

     if(!NT_SUCCESS(st))
     {
       SetLastNTError(RtlNtStatusToDosError(st));
       return NULL;
     }
   }

   if(FileHandle == INVALID_HANDLE_VALUE)
   {
     // FileHandle 参数为 INVALID_HANDLE_VALUE 时 ExistingCompletionPort 参数必须为空
     if(ExistingCompletionPort != NULL)
     {
       CompletionPort = NULL;
       BaseSetLastNTError(STATUS_INVALID_PARAMETER);
     }

     // 只创建完成端口对象，但并不绑定 I/O 句柄到完成端口上
     return CompletionPort;
   }

   IO_STATUS_BLOCK blk;

   // 将 I/O 句柄绑定到完成端口上
   NTSTATUS st = NtSetInformationFile(FileHandle, &blk, &CompletionKey, 8, FileCompletionInformation);

   if(NT_SUCCESS(st))
   {
     return CompletionPort;
   }
   else
   {
     SetLastNTError(RtlNtStatusToDosError(st));

     if(CompletionPort)
     {
       CloseHandle(CompletionPort);
     }

     return NULL;
   }
}

     CloseHandle 在处理完成端口时则直接调用 IopDeleteIoCompletion 函数(iocomplete.c:675)。而 GetQueuedCompletionStatus 函数和 PostQueuedCompletionStatus 函数，则分别是 NtRemoveIoCompletion 函数(iocomplete.c:485)和 NtSetIoCompletion 函数(iocomplete.c:417)的简单包装。    

以下为引用：

BOOL GetQueuedCompletionStatus(HANDLE CompletionPort, LPDWORD lpNumberOfBytes,
   PULONG_PTR lpCompletionKey, LPOVERLAPPED* lpOverlapped, DWORD dwMilliseconds)
{
   LARGE_INTEGER Timeout;
  
   BaseFormatTimeOut(&Timeout, dwMilliseconds);
  
   IO_STATUS_BLOCK blk;
  
   NTSTATUS st = NtRemoveIoCompletion(CompletionPort, lpCompletionKey, &dwMilliseconds, &blk, &Timeout);
  
   if(FAILED(st) || st == STATUS_TIMEOUT)
   {
     // 设置错误代码
   }
   else
   {
     if(SUCCEEDED(blk.Status))
     {
       // 设置 lpOverlapped 和 lpNumberOfBytes
     }
   }
}  

     从实现角度来看，完成端口实际上是一个 IoCompletionObjectType 类型的内核对象，其对象体就是一个 KQUEUE 结构维护的内核队列。创建此内核对象类型信息的代码如下(io/ioinit.c:1527)：

以下为引用：

//
// Create the object type for I/O completion objects.
//

RtlInitUnicodeString( &nameString, L"IoCompletion" );                    // 对象名称
objectTypeInitializer.DefaultNonPagedPoolCharge = sizeof( KQUEUE );      // 对象体
objectTypeInitializer.InvalidAttributes = OBJ_PERMANENT | OBJ_OPENLINK;
objectTypeInitializer.GenericMapping = IopCompletionMapping;
objectTypeInitializer.ValidAccessMask = IO_COMPLETION_ALL_ACCESS;
objectTypeInitializer.DeleteProcedure = IopDeleteIoCompletion;           // CloseHandle 调用函数
if (!NT_SUCCESS( ObCreateObjectType( &nameString, &objectTypeInitializer,
   (PSECURITY_DESCRIPTOR) NULL, &IoCompletionObjectType )))
{
   return FALSE;
}

     NtCreateIoCompletion 函数(iocomplete.c:51)只是简单地构造并初始化这个内核对象。
     首先对来自用户态的调用验证 IoCompletionHandle 参数指向内存可写；然后调用 ObCreateObject 函数构造内核对象；如果成功则调用 KeInitializeQueue 函数初始化内核队列；并且调用 ObInsertObject 函数将内核对象加入到当前进程的句柄表中；最后将构造的内核对象的句柄返回给调用者。伪代码如下：

以下为引用：

NTSTATUS
NtCreateIoCompletion (
   IN PHANDLE IoCompletionHandle,
   IN ACCESS_MASK DesiredAccess,
   IN POBJECT_ATTRIBUTES ObjectAttributes OPTIONAL,
   IN ULONG Count OPTIONAL)
{
   NTSTATUS st;
   try
   {
     // 对来自用户态的调用验证 IoCompletionHandle 参数指向内存可写
     if(KeGetPreviousMode() != KernelMode)
     {
       ProbeForWriteHandle(IoCompletionHandle);
     }

     PVOID IoCompletion; // 完成端口内核对象

     // 构造内核对象
     st = ObCreateObject(..., IoCompletionObjectType, ..., sizeof(KQUEUE), ..., &IoCompletion);

     if(NT_SUCCESS(st))
     {
       // 初始化内核队列
       KeInitializeQueue((PKQUEUE)IoCompletion, Count);

       HANDLE Handle;

       // 将内核对象加入到当前进程的句柄表中
       st = ObInsertObject(IoCompletion, ..., &Handle);

       if(NT_SUCCESS(st))
       {
         try
         {
           // 将构造的内核对象的句柄返回给调用者
           *IoCompletionHandle = Handle;
         }
         catch(...)
         {
           // 完成端口内核对象已创建并插入当前进程句柄表，因此需要忽略错误
         }
       }
     }
   }
   catch(...)
   {
     st = GetExceptionCode();
   }
   return st;
}

     系统还提供了一个相应的 NtOpenIoCompletion 函数(iocomplete.c:178)支持打开已经建立的有名字的完成端口。其调用 ObOpenObjectByName 函数完成名字到内核对象的映射，并最终将完成端口对象句柄返回给调用者。伪代码如下：

以下为引用：

NTSTATUS
NtOpenIoCompletion (
   OUT PHANDLE IoCompletionHandle,
   IN ACCESS_MASK DesiredAccess,
   IN POBJECT_ATTRIBUTES ObjectAttributes)
{
   NTSTATUS st;
   try
   {
     // 对来自用户态的调用验证 IoCompletionHandle 参数指向内存可写
     if(KeGetPreviousMode() != KernelMode)
     {
       ProbeForWriteHandle(IoCompletionHandle);
     }

     HANDLE Handle;

     st = ObOpenObjectByName(ObjectAttributes, IoCompletionObjectType, ..., DesiredAccess, ..., &Handle);

     if(NT_SUCCESS(st))
     {
       try
       {
         // 将构造的内核对象的句柄返回给调用者
         *IoCompletionHandle = Handle;
       }
       catch(...)
       {
       }
     }
   }
   catch(...)
   {
     st = GetExceptionCode();
   }
   return st;
}

     在建立了完成端口对象后，可以通过 NtQueryIoCompletion 函数(iocomplete.c:282)查询此完成端口队列中阻塞的 I/O 完成包的数量。此函数实际上是对读取内核队列状态 KeReadStateQueue 函数(kequeueobj.c:92)的封装，从 KQUEUE::Header::SignalState 字段读取完成端口内部使用的内核队列对象的阻塞深度。
     NtRemoveIoCompletion 函数(iocomplete.c:485)和 NtSetIoCompletion 函数(iocomplete.c:417) 实际上也只是直接调用内核队列维护函数 KeRemoveQueue 函数(kequeueobj.c:238) 和 KeRundownQueue 函数(kequeueobj.c:566) 完成对内核队列的操作。

     在构造和初始化完成端口内核对象后，需要开始对完成端口进行操作，以实现对完成端口获取或发送完成包的操作。而这些操作归根结底实际上都是对内核队列进行操作，因此得先对内核队列有所了解。我会单独写一篇 BLog 讨论内核对象的实现思路，这里暂且不深入讨论。