HTTPAPI | FineTune

TsgcWSServer_HTTPAPI 公开了一个名为 FineTune 的已发布属性，类型为 TsgcServerHTTPAPI_FineTune。它汇集了影响 Windows HTTP Server API（http.sys）如何对请求进行排队、分发和完成的底层内核模式调节项。

QueueLength

包装 HttpServerQueueLengthProperty 内核设置。它控制 http.sys 在服务器从队列中取出请求之前在内核模式队列中保存的最大待处理请求数。当队列满时，内核直接以 503 Service Unavailable 响应新连接，而不会进入用户模式。

Type：ULONG。

默认值：1000（Windows 内核默认值）。

范围： 最多 65535 个请求。

改进效果：提高此值可防止内核在突发工作负载下拒绝合法流量，例如 IoT 设备群在网络中断后的重连、市场数据广播客户端在提供商重置后的重连，或所有工作节点在共享 cron 任务触发时同时连接的场景。

SkipIOCPOnSuccess

当设置为 True 时，服务器使用标志 FILE_SKIP_COMPLETION_PORT_ON_SUCCESS 和 FILE_SKIP_SET_EVENT_ON_HANDLE 在请求队列句柄上调用 SetFileCompletionNotificationModes。同步完成的请求队列上的重叠 I/O 操作将不再向 I/O 完成端口发布额外的完成数据包。

类型： Boolean。

默认值：False（未设置任何标志，保留当前行为）。

改进内容：当调用同步返回 NO_ERROR 时，消除热请求路径上的内核到用户模式切换——工作线程在调用线程上内联分发完成，而无需等待 IOCP 数据包。这是 Microsoft 参考 HTTP Server High Performance 示例所使用的模式。该标志旨在与 OperatingMode = ompHighPerf 配合使用。

API 在运行时通过 GetProcAddress 从 kernel32 解析。在 Windows XP 及更早版本（Delphi 7 运行时目标）上，该入口点不存在，包装器返回 False，服务器在未设置该标志的情况下运行。

OperatingMode

选择两种接受/调度架构之一。

Type：TsgcHTTPAPIOperatingMode = (ompClassic, ompHighPerf)。

默认值： ompClassic。

ompClassic — 单个接受线程同步调用 HttpReceiveHttpRequest，并通过 PostQueuedCompletionStatus 将每个请求手动分发到 IOCP 工作线程池。这是历史上的默认行为。
ompHighPerf — 实现 Microsoft 参考 HTTP 服务器高性能模式。acceptor 线程被移除。启动时，服务器在绑定 IOCP 的队列上预发布 ThreadPoolSize x HighPerfAcceptsPerWorker 个异步接收（默认为 32 x 4 = 128 个并发挂起接收）。每个工作线程内联处理其完成通知并重新发布一个异步接收，维持一个滑动窗口直到关闭。

改进说明：当服务器遇到深度单流管道（大帧上传/下载）或大量并发客户端（数百至数千）时，ompHighPerf 的优势最为明显。预投递接收窗口可吸收突发流量而无需按连接分配，内联分发消除了接受者切换瓶颈。对于低流量 API 和开发环境，请保留默认的 ompClassic，在轻负载下维护 128 个预投递上下文的开销大于其带来的收益。此模式只能在服务器激活前更改。

HighPerfAcceptsPerWorker

控制当 OperatingMode = ompHighPerf 时每个 IOCP 工作线程预发布的异步接收数量。在 ompClassic 模式下忽略此值。服务器维护的并发未完成接收总数等于 ThreadPoolSize x HighPerfAcceptsPerWorker。

Type：整数。

默认值：4。

改进内容：更深的每工作线程窗口允许服务器在热路径上无需分配新上下文即可吸收更大的突发入站请求。对于高并发部署（IoT 设备群、市场数据分发、扇出代理），请适当提高该值；代价是内存——每个预投递接收持有一个约 16 KB 的请求缓冲区，直到完成前一直保留。默认值 4 是经过 MSDN HP 示例验证的保守折中值。

示例

以下代码片段为高并发 IoT 后端配置了 HTTP.sys 服务器：使用大型内核队列以吸收重连风暴，使用 HighPerf 分发模式并扩展预投递接收窗口，并启用内联完成分发。


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;
  // dispatch inline on sync-success completions; skip the IOCP round-trip
  oServer.FineTune.SkipIOCPOnSuccess := True;
  oServer.Active := True;
end;

对于典型的内部或低流量 API，请将每个 FineTune 属性保留为默认值：


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