perf(epoll): run the HTTP pipeline inline in the worker instead of hopping through TTask.Run

doc/epoll.md

@@ -84,3 +84,31 @@ end.
 ```
 
 The framework will resolve the `THorse.Listen` call to the native epoll reactor when running under Linux.
+
+## Pipeline execution modes (Delphi)
+
+By default, route handlers run in a bounded pool owned by the epoll provider. This keeps blocking handlers (database access, filesystem operations, or remote calls) away from the I/O event-loop threads without changing Delphi's process-wide `TThreadPool.Default` settings.
+
+The default worker count is eight times the processor count and the default pending-request queue capacity is 2048. Configure either value before calling `Listen`:
+
+```delphi
+uses
+  Horse,
+  Horse.Provider.Epoll;
+
+begin
+  THorseProviderEpoll.PipelineWorkerThreads := 32; // 0 = automatic
+  THorseProviderEpoll.PipelineQueueCapacity := 1024;
+  THorse.Listen(9095);
+end.
+```
+
+Applications whose handlers are known to be short and non-blocking can opt into inline execution:
+
+```delphi
+THorseProviderEpoll.PipelineMode := epmInline;
+```
+
+Inline mode removes the dispatch hop and can improve throughput and tail latency for very short handlers. It also means that one slow handler blocks its epoll worker and delays every connection assigned to that event loop. Do not use inline mode for handlers that perform blocking I/O. Pipeline settings cannot be changed while the provider is running.
+
+When the bounded queue is full, the provider closes the newly saturated connection instead of creating more threads or silently losing the request. During shutdown, it stops accepting work and drains requests already accepted by the pipeline pool before releasing their connection contexts.

doc/epoll.pt-BR.md

@@ -84,3 +84,31 @@ end.
 ```
 
 O framework resolverá automaticamente a chamada de `THorse.Listen` para o reactor nativo epoll quando executado em ambientes Linux.
+
+## Modos de execução da pipeline (Delphi)
+
+Por padrão, os handlers das rotas são executados em um pool limitado pertencente ao próprio provider epoll. Isso mantém handlers bloqueantes (acesso ao banco de dados, filesystem ou chamadas remotas) fora das threads do event loop sem alterar as configurações globais de `TThreadPool.Default` do processo Delphi.
+
+A quantidade padrão de workers é oito vezes a quantidade de processadores e a capacidade padrão da fila de requisições pendentes é 2048. Configure esses valores antes de chamar `Listen`:
+
+```delphi
+uses
+  Horse,
+  Horse.Provider.Epoll;
+
+begin
+  THorseProviderEpoll.PipelineWorkerThreads := 32; // 0 = automático
+  THorseProviderEpoll.PipelineQueueCapacity := 1024;
+  THorse.Listen(9095);
+end.
+```
+
+Aplicações cujos handlers sejam comprovadamente curtos e não bloqueantes podem optar pela execução inline:
+
+```delphi
+THorseProviderEpoll.PipelineMode := epmInline;
+```
+
+O modo inline elimina o despacho para outra thread e pode melhorar throughput e latência de cauda para handlers muito curtos. Em contrapartida, um único handler lento bloqueia seu worker epoll e atrasa todas as conexões atribuídas àquele event loop. Não use o modo inline em handlers que realizem E/S bloqueante. As configurações da pipeline não podem ser alteradas enquanto o provider estiver em execução.
+
+Quando a fila limitada está cheia, o provider fecha a nova conexão saturada em vez de criar mais threads ou perder silenciosamente a requisição. Durante o shutdown, ele deixa de aceitar trabalho e drena as requisições já aceitas pelo pool antes de liberar os contexts das conexões.