path: root/guide
diff options
authorLoïc Hoguin <[email protected]>2013-01-18 20:22:49 +0100
committerLoïc Hoguin <[email protected]>2013-01-18 20:22:49 +0100
commit6d98b320ff44909887b0007eb63340f69157c11f (patch)
tree21d5e9de9448858c10faed95f35c1ea0377d822c /guide
parenta27296b34d3dc2481f0e3c013b7548690db26b01 (diff)
Finish up the Internals chapter
Diffstat (limited to 'guide')
2 files changed, 49 insertions, 6 deletions
diff --git a/guide/internals.md b/guide/internals.md
index 3179b9f..0f8adc2 100644
--- a/guide/internals.md
+++ b/guide/internals.md
@@ -4,7 +4,38 @@ Internals
-@todo Describe.
+Cowboy is a lightweight HTTP server.
+It is built on top of Ranch. Please see the Ranch guide for more
+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.
+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.
+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.
+One process for many requests
+As previously mentioned, Cowboy only use one process per connection.
+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
Lowercase header names
@@ -30,8 +61,19 @@ capitalize_hook(Status, Headers, Body, Req) ->
-Efficiency considerations
+Improving performance
+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.
+Another option is to define platform-specific socket options that
+are known to improve their efficiency.
-@todo Mention that you need to cleanup in terminate especially if you
-used the process dictionary, started timers, started monitoring...
+Please see the Ranch guide for more information.
diff --git a/guide/toc.md b/guide/toc.md
index 528f8c6..b4131c5 100644
--- a/guide/toc.md
+++ b/guide/toc.md
@@ -49,5 +49,6 @@ Cowboy User Guide
* Handler middleware
* [Internals](internals.md)
* Architecture
+ * One process for many requests
* Lowercase header names
- * Efficiency considerations
+ * Improving performance