Add a skeleton performance chapter to the guide

3 files changed, 32 insertions, 1 deletions

diff --git a/doc/src/guide/book.asciidoc b/doc/src/guide/book.asciidoc
index f5989eb..76557a6 100644
--- a/doc/src/guide/book.asciidoc
+++ b/doc/src/guide/book.asciidoc
@@ -71,6 +71,8 @@ include::streams.asciidoc[Streams]
 
 include::middlewares.asciidoc[Middlewares]
 
+include::performance.asciidoc[Performance]
+
 = Additional information
 
 include::migrating_from_2.6.asciidoc[Migrating from Cowboy 2.6 to 2.7]
diff --git a/doc/src/guide/performance.asciidoc b/doc/src/guide/performance.asciidoc
new file mode 100644
index 0000000..1003130
--- /dev/null
+++ b/doc/src/guide/performance.asciidoc
@@ -0,0 +1,29 @@
+[[performance]]
+== Performance
+
+This chapter describes the performance characteristics
+of Cowboy and offers suggestions to get the most
+performance out of your application.
+
+=== One process per connection
+
+The first version of Cowboy featured a single process
+per connection, whereas the current version of Cowboy
+features one process per connection plus one process
+per request. This has a negative impact on performance,
+but is necessary in order to provide a common interface
+for both HTTP/1.1 and HTTP/2 (as well as future HTTP
+versions).
+
+It is still possible to use a single process per
+connection, and avoid the creation of additional
+processes for each request, by implementing a
+stream handler to process the requests. This can
+be done for all requests, or just for a single
+endpoint depending on the application's needs.
+
+Stream handlers provide an asynchronous interface
+and must not block, so the implementation will
+be very different from normal Cowboy handlers,
+but the performance gains are important enough
+to justify it in some cases.
diff --git a/doc/src/guide/streams.asciidoc b/doc/src/guide/streams.asciidoc
index 39b5203..0ac84ce 100644
--- a/doc/src/guide/streams.asciidoc
+++ b/doc/src/guide/streams.asciidoc
@@ -54,7 +54,7 @@ modified.
 
 === Built-in handlers
 
-Cowboy comes with two handlers.
+Cowboy comes with four handlers.
 
 link:man:cowboy_stream_h(3)[cowboy_stream_h] is the default
 stream handler. It is the core of much of the functionality