Tuning ad alte prestazioni di HTTP.SYS

· Funzionalità

A partire da sgcWebSockets 2026.5.0, il componente TsgcWSServer_HTTPAPI espone una nuova proprietà published, FineTune, di tipo TsgcServerHTTPAPI_FineTune. Raggruppa ogni parametro di basso livello in kernel mode che influenza il modo in cui la Windows HTTP Server API (http.sys) accoda, smista e completa le richieste. Finora questi parametri non esistevano sul componente oppure erano hardcoded — ora sono published, persistiti con la form e regolabili a design time.

La proprietà FineTune è un contenitore TPersistent con quattro sotto-proprietà: QueueLength, SkipIOCPOnSuccess, OperatingMode e HighPerfAcceptsPerWorker. Ognuna ha come valore predefinito un valore che preserva il comportamento esistente, quindi l'aggiornamento a 2026.5.0 non richiede alcuna modifica del codice; puoi abilitare ogni regolazione individualmente quando un workload specifico lo richiede.

Le proprietà FineTune

QueueLength : ULONG (predefinito 1000)

Cosa fa. Incapsula l'impostazione kernel HttpServerQueueLengthProperty. Controlla quante richieste in sospeso http.sys manterrà nella sua coda in kernel mode prima che il server le abbia dequeuate. Quando la coda è piena, il kernel risponde alle nuove connessioni con 503 Service Unavailable direttamente, senza mai raggiungere l'user mode.

Cosa migliora. In workload a raffica — migliaia di dispositivi IoT che si riconnettono dopo un blip di rete, rollout di flotte, picchi di traffico all'apertura del mercato — aumentare QueueLength impedisce al kernel di rifiutare i client prima che il tuo processo li veda, evitando retry a cascata sul client. Il default di 1000 corrisponde al default del kernel Windows ed è conservativo per i workload moderni; l'intervallo valido arriva fino a 65535.

SkipIOCPOnSuccess : Boolean (predefinito False)

Cosa fa. Quando impostato a True, abilita i flag FILE_SKIP_COMPLETION_PORT_ON_SUCCESS e FILE_SKIP_SET_EVENT_ON_HANDLE sull'handle della coda di richieste tramite SetFileCompletionNotificationModes. Il kernel quindi salta l'invio di un pacchetto di completamento all'IOCP quando un'operazione di I/O overlapped si completa in modo sincrono.

Cosa migliora. Elimina un salto kernel-to-user-mode sul percorso caldo della richiesta quando la chiamata restituisce NO_ERROR in modo sincrono — il worker smista il completamento inline sul thread chiamante invece di attendere un pacchetto IOCP. Questo è il pattern usato dall'esempio di riferimento di Microsoft "HTTP Server High Performance". Il default False è deliberato: abilitare il flag richiede una gestione lato chiamante dei completamenti inline. La proprietà è pensata per essere abbinata a OperatingMode = ompHighPerf nei workload in cui il guadagno di throughput giustifica il percorso di codice aggiuntivo.

OperatingMode : TsgcHTTPAPIOperatingMode (predefinito ompClassic)

Cosa fa. Seleziona una delle due architetture di accept/dispatch:

Cosa migliora. ompHighPerf conviene quando il server vede pipeline single-stream profonde (upload/download a frame grandi) o molti client concorrenti (centinaia o migliaia). La finestra di receive pre-postate assorbe le raffiche senza allocazioni per connessione e il dispatch inline rimuove il collo di bottiglia del passaggio dall'acceptor. Lascia il default ompClassic per API a basso traffico e ambienti di sviluppo — su workload leggeri il costo di mantenere 128 contesti pre-postati è superiore al risparmio. La modalità può essere modificata solo al momento della costruzione; mescolare modalità nello stesso ciclo di vita di processo non è supportato.

HighPerfAcceptsPerWorker : Integer (predefinito 4)

Cosa fa. Controlla quante receive asincrone ogni worker IOCP pre-posta quando OperatingMode = ompHighPerf. Il valore viene ignorato in modalità ompClassic. Il numero totale di receive concorrenti in attesa che il server mantiene equivale a ThreadPoolSize × HighPerfAcceptsPerWorker.

Cosa migliora. Una finestra per worker più profonda permette al server di assorbire raffiche più grandi di richieste in arrivo senza allocare nuovi contesti sul percorso caldo. Aumentalo per i deployment ad alta concorrenza (flotte IoT, distribuzione di market-data, broker fan-out); il compromesso è la memoria — ogni receive pre-postata trattiene un buffer di richiesta (~16 KB) riservato fino al completamento. Il default 4 è una via di mezzo conservativa validata rispetto all'esempio "HP" della MSDN.

Esempio d'uso

Il seguente snippet configura un server HTTP.sys per un backend IoT ad alta concorrenza: una grande coda kernel per assorbire le tempeste di riconnessione, dispatch HighPerf con finestra di receive pre-postata allargata e dispatch a completamento inline abilitato.

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;

Per un'API interna o a basso traffico, lascia ogni proprietà FineTune al suo valore predefinito:

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