diff options
Diffstat (limited to 'doc/src/guide')
| -rw-r--r-- | doc/src/guide/architecture.asciidoc | 48 | ||||
| -rw-r--r-- | doc/src/guide/book.asciidoc | 2 | ||||
| -rw-r--r-- | doc/src/guide/flow_diagram.asciidoc | 64 |
3 files changed, 58 insertions, 56 deletions
diff --git a/doc/src/guide/architecture.asciidoc b/doc/src/guide/architecture.asciidoc deleted file mode 100644 index 416ef36..0000000 --- a/doc/src/guide/architecture.asciidoc +++ /dev/null @@ -1,48 +0,0 @@ -[[architecture]] -== Architecture - -Cowboy is a lightweight HTTP server. - -It is built on top of Ranch. Please see the Ranch guide for more -information. - -=== One process per connection - -It uses only one process per connection. The process where your -code runs is the process controlling the socket. Using one process -instead of two allows for lower memory usage. - -Because there can be more than one request per connection with the -keepalive feature of HTTP/1.1, that means the same process will be -used to handle many requests. - -Because of this, you are expected to make sure your process cleans -up before terminating the handling of the current request. This may -include cleaning up the process dictionary, timers, monitoring and -more. - -=== Binaries - -It uses binaries. Binaries are more efficient than lists for -representing strings because they take less memory space. Processing -performance can vary depending on the operation. Binaries are known -for generally getting a great boost if the code is compiled natively. -Please see the HiPE documentation for more details. - -=== Date header - -Because querying for the current date and time can be expensive, -Cowboy generates one `Date` header value every second, shares it -to all other processes, which then simply copy it in the response. -This allows compliance with HTTP/1.1 with no actual performance loss. - -=== Max connections - -By default the maximum number of active connections is set to a -generally accepted big enough number. This is meant to prevent having -too many processes performing potentially heavy work and slowing -everything else down, or taking up all the memory. - -Disabling this feature, by setting the `{max_connections, infinity}` -protocol option, would give you greater performance when you are -only processing short-lived requests. diff --git a/doc/src/guide/book.asciidoc b/doc/src/guide/book.asciidoc index 3ab3cb6..162f28d 100644 --- a/doc/src/guide/book.asciidoc +++ b/doc/src/guide/book.asciidoc @@ -92,6 +92,4 @@ The following chapters were relevant in Cowboy 1.0. They have not been updated for Cowboy 2.0 yet. The information in these chapters may or may not be useful. -include::architecture.asciidoc[Architecture] - include::overview.asciidoc[Overview] diff --git a/doc/src/guide/flow_diagram.asciidoc b/doc/src/guide/flow_diagram.asciidoc index ad2110d..4cb3bda 100644 --- a/doc/src/guide/flow_diagram.asciidoc +++ b/doc/src/guide/flow_diagram.asciidoc @@ -1,12 +1,64 @@ [[flow_diagram]] == Flow diagram -Placeholder chapter. +Cowboy is a lightweight HTTP server with support for HTTP/1.1, +HTTP/2 and Websocket. -Cowboy 2.0 has changed the request flow and general architecture. -You can read about the Cowboy 1.0 architecture and flow here: +It is built on top of Ranch. Please see the Ranch guide for more +information about how the network connections are handled. -* xref:architecture[Architecture] -* xref:overview[Overview] +=== Overview -This chapter will be updated in a future pre-release. +Placeholder section. + +// @todo Make the diagram. + +=== Number of processes per connection + +By default, Cowboy will use one process per connection, +plus one process per set of request/response (called a +stream, internally). + +The reason it creates a new process for every request is due +to the requirements of HTTP/2 where requests are executed +concurrently and independently from the connection. The +frames from the different requests end up interleaved on +the single TCP connection. + +The request processes are never reused. There is therefore +no need to perform any cleanup after the response has been +sent. The process will terminate and Erlang/OTP will reclaim +all memory at once. + +Cowboy ultimately does not require more than one process +per connection. It is possible to interact with the connection +directly from a stream handler, a low level interface to Cowboy. +They are executed from within the connection process, and can +handle the incoming requests and send responses. This is however +not recommended in normal circumstances, as a stream handler +taking too long to execute could have a negative impact on +concurrent requests or the state of the connection itself. + +=== Date header + +Because querying for the current date and time can be expensive, +Cowboy generates one 'Date' header value every second, shares it +to all other processes, which then simply copy it in the response. +This allows compliance with HTTP/1.1 with no actual performance loss. + +=== Binaries + +Cowboy makes extensive use of binaries. + +Binaries are more efficient than lists for representing +strings because they take less memory space. Processing +performance can vary depending on the operation. Binaries +are known for generally getting a great boost if the code +is compiled natively. Please see the HiPE documentation +for more details. + +Binaries may end up being shared between processes. This +can lead to some large memory usage when one process keeps +the binary data around forever without freeing it. If you +see some weird memory usage in your application, this might +be the cause. |