SIO_LOOPBACK_FAST_PATH Control Code

Article
01/07/2021

Description

The SIO_LOOPBACK_FAST_PATH control code configures a TCP socket for lower latency and faster operations on the loopback interface.

Important The SIO_LOOPBACK_FAST_PATH is deprecated and is not recommended to be used in your code.

To perform this operation, call the WSAIoctl or WSPIoctl function with the following parameters.

int WSAIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_LOOPBACK_FAST_PATH,                // dwIoControlCode
  (LPVOID) lpvInBuffer,   // pointer to a Boolean value
  (DWORD) cbInBuffer,    // size, in bytes, of the input buffer
  (LPVOID) lpvOutBuffer,         // pointer to output buffer
  (DWORD) cbOutBuffer,       // size of output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
);

int WSPIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_LOOPBACK_FAST_PATH,                // dwIoControlCode
  (LPVOID) lpvInBuffer,   // pointer to a Boolean value
  (DWORD) cbInBuffer,           // size, in bytes, of the input buffer
  (LPVOID) lpvOutBuffer,         // pointer to output buffer
  (DWORD) cbOutBuffer,       // size of output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
  (LPWSATHREADID) lpThreadId,   // a WSATHREADID structure
  (LPINT) lpErrno   // a pointer to the error code.
);

Parameters

s

A descriptor identifying a socket.

dwIoControlCode

The control code for the operation. Use SIO_LOOPBACK_FAST_PATH for this operation.

lpvInBuffer

A pointer to the input buffer. This parameter contains a pointer to a Boolean value that indicates if the socket should be configured for fast loopback operations.

cbInBuffer

The size, in bytes, of the input buffer.

lpvOutBuffer

A pointer to the output buffer. This parameter is unused for this operation.

cbOutBuffer

The size, in bytes, of the output buffer. This parameter must be set to zero.

lpcbBytesReturned

A pointer to a variable that receives the size, in bytes, of the data stored in the output buffer.

If the output buffer is too small, the call fails, WSAGetLastError returns WSAEINVAL, and the lpcbBytesReturned parameter points to a DWORD value of zero.

If lpOverlapped is NULL, the DWORD value pointed to by the lpcbBytesReturned parameter that is returned on a successful call cannot be zero.

If the lpOverlapped parameter is not NULL for overlapped sockets, operations that cannot be completed immediately will be initiated, and completion will be indicated at a later time. The DWORD value pointed to by the lpcbBytesReturned parameter that is returned may be zero since the size of the data stored can't be determined until the overlapped operation has completed. The final completion status can be retrieved when the appropriate completion method is signaled when the operation has completed.

lpvOverlapped

A pointer to a WSAOVERLAPPED structure.

If socket s was created without the overlapped attribute, the lpOverlapped parameter is ignored.

If s was opened with the overlapped attribute and the lpOverlapped parameter is not NULL, the operation is performed as an overlapped (asynchronous) operation. In this case, lpOverlapped parameter must point to a valid WSAOVERLAPPED structure.

For overlapped operations, the WSAIoctl or WSPIoctl function returns immediately, and the appropriate completion method is signaled when the operation has been completed. Otherwise, the function does not return until the operation has been completed or an error occurs.

lpCompletionRoutine

Type: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

A pointer to the completion routine called when the operation has been completed (ignored for non-overlapped sockets).

lpThreadId

A pointer to a WSATHREADID structure to be used by the provider in a subsequent call to WPUQueueApc. The provider should store the referenced WSATHREADID structure (not the pointer to same) until after the WPUQueueApc function returns.

Note This parameter applies only to the WSPIoctl function.

lpErrno

A pointer to the error code.

Note This parameter applies only to the WSPIoctl function.

Return value

If the operation completes successfully, the WSAIoctl or WSPIoctl function returns zero.

If the operation fails or is pending, the WSAIoctl or WSPIoctl function returns SOCKET_ERROR. To get extended error information, call WSAGetLastError.

Error code	Meaning
WSA_IO_PENDING	Overlapped I/O operation is in progress. This value is returned if an overlapped operation was successfully initiated and completion will be indicated at a later time.
WSA_OPERATION_ABORTED	The I/O operation has been aborted because of either a thread exit or an application request. This error is returned if an overlapped operation was canceled due to the closure of the socket or the execution of the SIO_FLUSH IOCTL command.
WSAEACCES	An attempt was made to access a socket in a way forbidden by its access permissions. This error is returned under several conditions for persistent port reservations that include the following: the user lacks the required administrative privileges on the local computer or the application is not running in an enhanced shell as the built-in Administrator (`RunAs administrator`).
WSAEFAULT	The system detected an invalid pointer address in attempting to use a pointer argument in a call. This error is returned of the lpvInBuffer, lpvoutBuffer, lpcbBytesReturned, lpOverlapped or lpCompletionRoutine parameter is not totally contained in a valid part of the user address space.
WSAEINPROGRESS	A blocking operation is currently executing. This error is returned if the function is invoked when a callback is in progress.
WSAEINTR	A blocking operation was interrupted by a call to WSACancelBlockingCall. This error is returned if a blocking operation was interrupted.
WSAEINVAL	An invalid argument was supplied. This error is returned if the dwIoControlCode parameter is not a valid command, or a specified input parameter is not acceptable, or the command is not applicable to the type of socket specified.
WSAENETDOWN	A socket operation encountered a dead network. This error is returned if the network subsystem has failed.
WSAENOTSOCK	An operation was attempted on something that is not a socket. This error is returned if the descriptor s is not a socket.
WSAEOPNOTSUPP	The attempted operation is not supported for the type of object referenced. This error is returned if the specified IOCTL command is not supported. This error is also returned if the SIO_LOOPBACK_FAST_PATH IOCTL is not supported by the transport provider.

Remarks

An application can use the SIO_LOOPBACK_FAST_PATH IOCTL to reduce the latency and improve the performance of loopback operations on a TCP socket. This IOCTL requests that the TCP/IP stack uses a special fast path for loopback operations on this socket. The SIO_LOOPBACK_FAST_PATH IOCTL can be used only with TCP sockets. This IOCTL must be used on both sides of the loopback session. The TCP loopback fast path is supported using either the IPv4 or IPv6 loopback interface.

The socket that plans to initiate the connection request must apply this IOCTL before making the connection request. So the socket used by the connect, ConnectEx, WSAConnect, WSAConnectByList, or WSAConnectByName function to initiate the connection must apply this IOCTL to use the fast path for loopback operations.

The socket that is listening for the connection request must apply this IOCTL before accepting the connection. So the socket used by the listen function must apply this IOCTL so any sockets that are accepted will use the fast path for loopback. Any sockets returned by the listen function and passed to the accept, AcceptEx, or WSAAccept function will be marked to use the special fast path for loopback operations.

Once an application establishes the connection on a loopback interface using the fast path, all packets for the lifetime of the connection must use the fast path.

Applying SIO_LOOPBACK_FAST_PATH to a socket which will be connected to a non-loopback path will have no effect.

This TCP loopback optimization results in packets that flow through the Transport Layer (TL) instead of the traditional loopback through the Network Layer. This optimization improves the latency for loopback packets. Once an application opts in for a connection level setting to use the loopback fast path, all packets will follow the loopback path. For loopback communications, congestion and packet drop are not expected. The notion of congestion control and reliable delivery in TCP will be unnecessary. This, however, is not true for flow control. Without flow control, the sender can overwhelm the receive buffer, leading to erroneous TCP loopback behavior. The flow control in the TCP optimized loopback path is maintained by placing send requests in a queue. When receive buffer is full, the TCP/IP stack guarantees that the sends won't complete until the queue is serviced maintaining flow control.

TCP fast path loopback connections in the presence of a Windows Filtering Platform (WFP) callout for connection data must take the un-optimized slow path for loopback. So WFP filters will prevent this new loopback fast path from being used. When a WFP filter is enabled, the system we will use the slow path even if the SIO_LOOPBACK_FAST_PATH IOCTL was set. This ensures that user-mode applications have the full WFP security capability.

By default, SIO_LOOPBACK_FAST_PATH is disabled.

Only a subset of the TCP/IP socket options are supported when the SIO_LOOPBACK_FAST_PATH IOCTL is used to enable the loopback fast path on a socket. The list of supported options includes the following:

IP_TTL
IP_UNICAST_IF
IPV6_UNICAST_HOPS
IPV6_UNICAST_IF
IPV6_V6ONLY
SO_CONDITIONAL_ACCEPT
SO_EXCLUSIVEADDRUSE
SO_PORT_SCALABILITY
SO_RCVBUF
SO_REUSEADDR
TCP_BSDURGENT