Disable Nagle's algorithm in some examples

Author: trowski

README.md

@@ -136,12 +136,15 @@ $server->stop();
 
 The above example creates a simple server which sends a plain-text response to every request received.
 
+> **Note**
+> Nagle's algorithm can negatively affect benchmarks on some systems. It can be disabled using `Amp\Socket\BindContext::withTcpNoDelay()`, passing the returned instance as the second argument to `SocketHttpServer::expose()`.
+
 `SocketHttpServer` provides two static constructors for common use-cases in addition to the normal constructor for more advanced and custom uses.
 
-- `SocketHttpServer::createForDirectAccess()`: Used in the example above, this creates an HTTP application server suitable for direct network access. Adjustable limits are imposed on connections per IP, total connections, and concurrent requests (10, 1000, and 1000 by default, respectively). Response compression may be toggled on or off (on by default) and request methods are limited to a known set of HTTP verbs by default.
-- `SocketHttpServer::createForBehindProxy()`: Creates a server appropriate for use when behind a proxy service such as nginx. This static constructor requires a list of trusted proxy IPs (with optional subnet masks) and an enum case of `ForwardedHeaderType` (corresponding to either `Forwarded` or `X-Forwarded-For`) to parse the original client IP from request headers. No limits are imposed on the number of connections to the server, however the number of concurrent requests are limited (1000 by default, adjustable or can be removed). Response compression may be toggled on or off (on by default). Request methods are limited to a known set of HTTP verbs by default.
+- `SocketHttpServer::createForDirectAccess()`: Used in the example above, this creates an HTTP application server suitable for direct network access. Adjustable limits are imposed on connections per IP, total connections, and concurrent requests (10, 1000, and 1000 by default, respectively). Response compression may be toggled on or off (on by default), and request methods are limited to a known set of HTTP verbs by default.
+- `SocketHttpServer::createForBehindProxy()`: Creates a server appropriate for use when behind a proxy service such as nginx. This static constructor requires a list of trusted proxy IPs (with optional subnet masks) and an enum case of `ForwardedHeaderType` (corresponding to either `Forwarded` or `X-Forwarded-For`) to parse the original client IP from request headers. No limits are imposed on the number of connections to the server, however the number of concurrent requests is limited (1000 by default, adjustable or can be removed). Response compression may be toggled on or off (on by default). Request methods are limited to a known set of HTTP verbs by default.
 
-If neither of these methods serve your application needs, the `SocketHttpServer` constructor may be used directly. This provides an enormous amount of flexibility in how incoming connections client connections are created and handled, but will require more code to create. The constructor requires the user to pass an instance of `SocketServerFactory`, used to create client `Socket` instances (both components of the [`amphp/socket`](https://github.com/amphp/socket) library), and an instance of `ClientFactory`, which appropriately creates [`Client`](#request-clients) instances which are attached to each `Request` made by the client.
+If neither of these methods serves your application needs, the `SocketHttpServer` constructor may be used directly. This provides an enormous amount of flexibility in how incoming client connections are created and handled, but will require more code to create. The constructor requires the user to pass an instance of `SocketServerFactory`, used to create client `Socket` instances (both components of the [`amphp/socket`](https://github.com/amphp/socket) library), and an instance of `ClientFactory`, which appropriately creates [`Client`](#request-clients) instances which are attached to each `Request` made by the client.
 
 ### `RequestHandler`
 

examples/event-source.php

@@ -13,6 +13,7 @@
 use Amp\Http\Server\SocketHttpServer;
 use Amp\Log\ConsoleFormatter;
 use Amp\Log\StreamHandler;
+use Amp\Socket\BindContext;
 use Monolog\Logger;
 use Monolog\Processor\PsrLogMessageProcessor;
 use function Amp\delay;
@@ -48,8 +49,14 @@
 
 $server = SocketHttpServer::createForDirectAccess($logger);
 
-$server->expose("0.0.0.0:1337");
-$server->expose("[::]:1337");
+// BindContext::withTcpNoDelay() returns a context which disables Nagle's algorithm, decreasing
+// latency when responses are very small (as is the case here). This generally is not necessary
+// for a production server but can negatively affect benchmarks.
+
+$bindContext = (new BindContext())->withTcpNoDelay();
+
+$server->expose("0.0.0.0:1337", $bindContext);
+$server->expose("[::]:1337", $bindContext);
 
 $server->start(new ClosureRequestHandler(function (Request $request) use ($html): Response {
     $path = $request->getUri()->getPath();

examples/hello-world.php

@@ -14,6 +14,7 @@
 use Amp\Log\ConsoleFormatter;
 use Amp\Log\StreamHandler;
 use Amp\Socket;
+use Amp\Socket\BindContext;
 use Monolog\Logger;
 use Monolog\Processor\PsrLogMessageProcessor;
 use function Amp\trapSignal;
@@ -22,7 +23,12 @@
 
 $cert = new Socket\Certificate(__DIR__ . '/../test/server.pem');
 
-$context = (new Socket\BindContext)
+// BindContext::withTcpNoDelay() returns a context which disables Nagle's algorithm, decreasing
+// latency when responses are very small (as is the case here). This generally is not necessary
+// for a production server but can negatively affect benchmarks.
+$plainBindContext = (new BindContext)->withTcpNoDelay();
+
+$tlsBindContext = $plainBindContext
         ->withTlsContext((new Socket\ServerTlsContext)
                 ->withDefaultCertificate($cert));
 
@@ -39,10 +45,10 @@
     new SocketClientFactory($logger),
 );
 
-$server->expose("0.0.0.0:1337");
-$server->expose("[::]:1337");
-$server->expose("0.0.0.0:1338", $context);
-$server->expose("[::]:1338", $context);
+$server->expose("0.0.0.0:1337", $plainBindContext);
+$server->expose("[::]:1337", $plainBindContext);
+$server->expose("0.0.0.0:1338", $tlsBindContext);
+$server->expose("[::]:1338", $tlsBindContext);
 
 $server->start(new class implements RequestHandler {
     public function handleRequest(Request $request): Response

examples/state.php

@@ -12,6 +12,7 @@
 use Amp\Http\Server\SocketHttpServer;
 use Amp\Log\ConsoleFormatter;
 use Amp\Log\StreamHandler;
+use Amp\Socket\BindContext;
 use Monolog\Logger;
 use Monolog\Processor\PsrLogMessageProcessor;
 use function Amp\trapSignal;
@@ -24,10 +25,16 @@
 $logger = new Logger('server');
 $logger->pushHandler($logHandler);
 
+// BindContext::withTcpNoDelay() returns a context which disables Nagle's algorithm, decreasing
+// latency when responses are very small (as is the case here). This generally is not necessary
+// for a production server but can negatively affect benchmarks.
+
+$bindContext = (new BindContext())->withTcpNoDelay();
+
 $server = SocketHttpServer::createForDirectAccess($logger);
 
-$server->expose("0.0.0.0:1337");
-$server->expose("[::]:1337");
+$server->expose("0.0.0.0:1337", $bindContext);
+$server->expose("[::]:1337", $bindContext);
 
 $server->start(new ClosureRequestHandler(function (Request $request): Response {
     static $counter = 0;