Contents:

1 관련서적 #

• NETWORK PROGRAMMING FOR MICROSOFT WINDOWS
  • Anthony Jones.Jim Ohlund 공저, 김남식 역, 정보문화사
    
    

2 CreateIoCompletionPort() 함수 #

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

2.1 인수 #

• FileHandle
  [in] Handle to a file opened for overlapped I/O completion. You must specify the FILE_FLAG_OVERLAPPED flag when using the CreateFile function to obtain the handle.
  
  If FileHandle specifies INVALID_HANDLE_VALUE, CreateIoCompletionPort creates an I/O completion port without associating it with a file. In this case, the ExistingCompletionPort parameter must be NULL and the CompletionKey parameter is ignored.
  
  
• ExistingCompletionPort
  [in] Handle to the I/O completion port.
  
  If this parameter specifies an existing completion port, the function associates it with the file specified by the FileHandle parameter. The function returns the handle of the existing completion port; it does not create a new I/O completion port.
  
  If this parameter is NULL, the function creates a new I/O completion port and associates it with the file specified by FileHandle. The function returns the handle to the new I/O completion port.
  
  
• CompletionKey
  [in] Per-file completion key that is included in every I/O completion packet for the specified file.
  
  
• NumberOfConcurrentThreads
  [in] Maximum number of threads that the operating system can allow to concurrently process I/O completion packets for the I/O completion port. If this parameter is zero, the system allows as many concurrently running threads as there are processors in the system.
  
  Although any number of threads can call the GetQueuedCompletionStatus function to wait for an I/O completion port, each thread is associated with only one completion port at a time. That port is the port that was last checked by the thread.
  
  When a packet is queued to a port, the system first checks how many threads associated with the port are running. If the number of threads running is less than the value of NumberOfConcurrentThreads, then one of the waiting threads is allowed to process the packet. When a running thread completes its processing, it calls GetQueuedCompletionStatus again, at which point the system can allow another waiting thread to process a packet.
  
  The system also allows a waiting thread to process a packet if a running thread enters any wait state. When the thread in the wait state begins running again, there may be a brief period when the number of active threads exceeds the NumberOfConcurrentThreads value. However, the system quickly reduces the number by not allowing any new active threads until the number of active threads falls below the specified value.
  
  

2.2 반환값 #

3 GetQueuedCompletionStatus() 함수 #

BOOL GetQueuedCompletionStatus(
	HANDLE         CompletionPort,
	LPDWORD        lpNumberOfBytes,
	PULONG_PTR     lpCompletionKey,
	LPOVERLAPPED * lpOverlapped,
	DWORD          dwMilliseconds
);

3.1 인수 #

• CompletionPort
  [in] Handle to the completion port of interest. To create a completion port, use the CreateIoCompletionPort function.
  
  
• lpNumberOfBytes
  [out] Pointer to a variable that receives the number of bytes transferred during an I/O operation that has completed.
  
  
• lpCompletionKey
  [out] Pointer to a variable that receives the completion key value associated wit h the file handle whose I/O operation has completed. A completion key is a per-file key that is specified in a call to CreateIoCompletionPort.
  
  
• lpOverlapped
  [out] Pointer to a variable that receives the address of the OVERLAPPED structure that was specified when the completed I/O operation was started.
  
  The following functions can be used to start I/O operations that complete using completion ports. You must pass the function an OVERLAPPED structure and a file handle associated with an comp letion port (by a call to CreateIoCompletionPort) to invoke the I/O completion port mechanism:
  
  
  • ConnectNamedPipe
  • DeviceIoControl
  • LockFileEx
  • ReadDirectoryChangesW
  • ReadFile
  • TransactNamedPipe
  • WaitCommEvent
  • WriteFile
    
    
Even if you have passed the function a file handle associated with a completion port and a valid OVERLAPPED structure, an application can prevent completion port notification. This is done by specifying a valid event handle for the hEvent member of the OVERLAPPED structure, and setting its low-order bit. A valid event handle whose low-order bit is set keeps I/O completion from being queued to the completion port.


• dwMilliseconds
  [in] Number of milliseconds that the caller is willing to wait for an completion packet to appear at the completion port. If a completion packet doesn't appear within the specified time, the function times out, returns FALSE, and sets *lpOverlapped to NULL.
  
  If dwMilliseconds is INFINITE, the function will never time out. If dwMilliseconds is zero and there is no I/O operation to dequeue, the function will time out immediately.
  
  
  

3.2 반환값 #

Completion port 로부터 I/O 동작 완료 통지를 받았을 경우, 0 이 아닌 값을 반환한다. 이때 함수는 lpNumberOfBytesTransferred 와 lpCompletionKey, lpOverlapped 인수에 이와 관련된 정보들을 반환한다.

*lpOverlapped 값이 NULL 이고 Completion port 로부터 동작 완료 통지를 못받았을 경우, 0 을 반환한다. 이때 함수는 lpNumberOfBytes 와 lpCompletionKey 인수에 이와 관련된 정보를 저장하지 않는다. 에러 정보를 얻기 위해서는 GetLastError() 함수를 호출한다. 만약 타임-아웃에 의하여 완료통지를 못받았을 경우 GetLastError() 함수는 WAIT_TIMEOUT 를 반환한다.

*lpOverlapped 값이 NULL 이 아니고 Completion port 로부터 동작 완료 실패 통지를 받았을 경우, 0 을 반환한다. 이때 함수는 lpNumberOfBytes 와 lpCompletionKey, lpOverlapped 인수에 이와 관련된 정보를 저장한다. 에러 정보를 얻기 위해서는 GetLastError() 함수를 호출한다.

Completion port 와 연관된 소켓 핸들을 닫겼을 경우, GetQueuedCompletionStatus() 함수는 ERROR_SUCCESS 를 반환하며 lpNumberOfBytes 인수는 0 이 된다.

4 PostQueuedCompletionStatus() 함수 #

BOOL PostQueuedCompletionStatus(
	HANDLE       CompletionPort,
	DWORD        dwNumberOfBytesTransferred,
	ULONG_PTR    dwCompletionKey,
	LPOVERLAPPED lpOverlapped
);

4.1 인수 #

• CompletionPort
  [in] Handle to an I/O completion port to which the I/O completion packet is to be posted.
  
  
• dwNumberOfBytesTransferred
  [in] Value to be returned through the lpNumberOfBytesTransferred parameter of the GetQueuedCompletionStatus function.
  
  
• dwCompletionKey
  [in] Value to be returned through the lpCompletionKey parameter of the GetQueuedCompletionStatus function.
  
  
• lpOverlapped
  [in] Value to be returned through the lpOverlapped parameter of the GetQueuedCompletionStatus function.
  
  

4.2 반환값 #

SubCategoryNetwork