HTTPAPI | FineTune

TsgcWSServer_HTTPAPI exposes a published property named FineTune of type TsgcServerHTTPAPI_FineTune. It groups the low-level kernel-mode knobs that influence how the Windows HTTP Server API (http.sys) queues, dispatches and completes requests.

 

QueueLength

Wraps the HttpServerQueueLengthProperty kernel setting. It controls the maximum number of pending requests http.sys will hold in its kernel-mode queue before the server has dequeued them. When the queue is full, the kernel responds to new connections with 503 Service Unavailable directly, without ever reaching user mode.

 

Type: ULONG.

Default: 1000 (the Windows kernel default).

Range: up to 65535 requests.

What it improves: raising this value prevents the kernel from rejecting legitimate traffic on bursty workloads - IoT fleets reconnecting after a network blip, market-data broadcast clients reconnecting after a provider reset, or scheduled job workers that all connect on a shared cron tick.

 

SkipIOCPOnSuccess

This option is not supported and setting it has no effect. The property is kept only for compatibility, so existing forms and code that use it still load.

 

Type: Boolean.

Default: False.

Why it is not supported: the overlapped I/O of the server relies on a completion packet for every call, even when the call succeeds at once.

 

OperatingMode

Selects one of two accept/dispatch architectures.

 

Type: TsgcHTTPAPIOperatingMode = (ompClassic, ompHighPerf).

Default: ompClassic.

 

• ompClassic - single acceptor thread calls HttpReceiveHttpRequest synchronously and hand-dispatches each request to the IOCP worker pool via PostQueuedCompletionStatus. This is the historical behavior.
• ompHighPerf - implements Microsoft's reference HTTP Server High Performance pattern. The acceptor thread is removed. At startup the server pre-posts ThreadPoolSize x HighPerfAcceptsPerWorker async receives on the queue-bound IOCP (defaults to 32 x 4 = 128 concurrent outstanding receives). Each worker services its completion inline and re-posts another async receive, maintaining a sliding window until shutdown.

 

What it improves: ompHighPerf pays off when the server sees either deep single-stream pipelines (large-frame uploads/downloads) or many concurrent clients (hundreds to thousands). The pre-posted receive window absorbs bursts without per-connection allocation, and the inline dispatch removes the acceptor hand-off bottleneck. Leave the default ompClassic for low-traffic APIs and development environments - on light workloads the overhead of maintaining 128 pre-posted contexts costs more than it saves. The mode can only be changed before the server is activated.

 

HighPerfAcceptsPerWorker

Controls how many async receives each IOCP worker pre-posts when OperatingMode = ompHighPerf. The value is ignored in ompClassic mode. The total number of concurrent outstanding receives the server maintains equals ThreadPoolSize x HighPerfAcceptsPerWorker.

 

Type: Integer.

Default: 4.

What it improves: a deeper per-worker window lets the server absorb larger bursts of incoming requests without allocating new contexts on the hot path. Raise it for high-concurrency deployments (IoT fleets, market-data distribution, fan-out brokers); the tradeoff is memory - each pre-posted receive holds a request buffer (~16 KB) reserved until it completes. The default 4 is a conservative middle ground validated against the MSDN HP sample.

 

Example

The following snippet configures an HTTP.sys server for a high-concurrency IoT backend: a large kernel queue to absorb reconnect storms, and HighPerf dispatch with a widened pre-posted receive window.

 

uses
  sgcWebSocket_Server_HTTPAPI,
  sgcWebSocket_HTTPAPI_Server;   // TsgcHTTPAPIOperatingMode
var
  oServer: TsgcWSServer_HTTPAPI;
begin
  oServer := TsgcWSServer_HTTPAPI.Create(nil);
  oServer.Host := '0.0.0.0';
  oServer.Port := 8080;
  // absorb 10,000-device reconnect bursts before kernel-level 503
  oServer.FineTune.QueueLength := 10000;
  // switch from single-acceptor to pre-posted IOCP workers
  oServer.FineTune.OperatingMode := ompHighPerf;
  // widen the per-worker pre-posted receive window (32 threads * 8 = 256)
  oServer.FineTune.HighPerfAcceptsPerWorker := 8;
  oServer.Active := True;
end;

 

For a typical internal or low-traffic API, leave every FineTune property at its default:

 

oServer := TsgcWSServer_HTTPAPI.Create(nil);
oServer.Host := 'localhost';
oServer.Port := 8080;
// FineTune defaults: QueueLength=1000, SkipIOCPOnSuccess=False,
//                    OperatingMode=ompClassic, HighPerfAcceptsPerWorker=4
oServer.Active := True;