path: root/doc/src/manual/cowboy.start_clear.asciidoc
diff options
authorLoïc Hoguin <[email protected]>2016-09-25 17:32:41 +0200
committerLoïc Hoguin <[email protected]>2016-09-25 17:32:41 +0200
commit04247240629f1b9807feca34fde6de89286d4774 (patch)
tree3cb7cd41517b82d079d43a87e4902d39f4cd2c21 /doc/src/manual/cowboy.start_clear.asciidoc
parent31cabe0fb98b4c75cb088761ba5ad53dbd2285ee (diff)
Update manual for the cowboy module
This commit separates the documentation of the functions into separate manual pages, with at least one example per function and a lot more details about parameters, return values and related functions and modules. It also includes a changelog indicating when the function was added or changed. The inspiration for this comes mainly from the PHP documentation and feedback from users.
Diffstat (limited to 'doc/src/manual/cowboy.start_clear.asciidoc')
1 files changed, 126 insertions, 0 deletions
diff --git a/doc/src/manual/cowboy.start_clear.asciidoc b/doc/src/manual/cowboy.start_clear.asciidoc
new file mode 100644
index 0000000..4903426
--- /dev/null
+++ b/doc/src/manual/cowboy.start_clear.asciidoc
@@ -0,0 +1,126 @@
+= cowboy:start_clear(3)
+== Name
+cowboy:start_clear - Listen for connections using plain TCP
+== Description
+start_clear(Name :: ranch:ref(),
+ NumAcceptors :: non_neg_integer(),
+ TransportOpts :: ranch_tcp:opts(),
+ ProtocolOpts :: opts())
+ -> {ok, ListenerPid :: pid()}
+ | {error, any()}
+Start listening for connections over a clear TCP channel.
+Both HTTP/1.1 and HTTP/2 are supported on this listener.
+HTTP/2 has two methods of establishing a connection over
+a clear TCP channel. Both the upgrade and the prior knowledge
+methods are supported.
+== Arguments
+The listener name is used to refer to this listener in
+future calls, for example when stopping it or when
+updating the routes defined.
+It can be any Erlang term. An atom is generally good enough,
+for example `api`, `my_app_clear` or `my_app_tls`.
+The number of acceptors is the number of processes that
+will accept connections. Tweak this value to improve the
+accept rate for incoming connections.
+The ideal value is between 10 and 100 on most systems.
+Larger values may have the opposite effect and reduce the
+accept rate. It's generally safe to start with a value of
+100 (or 10 on low memory systems). Then, when accept rates
+become a concern, measure the performance and update the
+value accordingly.
+This value is unrelated to the maximum number of concurrent
+The transport options are where the TCP options, including
+the listener's port number, are defined. Transport options
+are provided as a list of keys and values, for example
+`[{port, 8080}]`.
+The available options are documented in the
+link:man:ranch_tcp(3)[ranch_tcp(3)] manual.
+The protocol options are in a map containing all the options for
+the different protocols that may be involved when connecting
+to the listener, including HTTP/1.1 and HTTP/2 but also
+subprotocols like Websocket.
+// @todo For Websocket this might change in the future.
+The HTTP/1.1 options are documented in the
+link:man:cowboy_http(3)[cowboy_http(3)] manual;
+the HTTP/2 options in
+and the Websocket options in
+== Return value
+An ok tuple is returned on success. It contains the pid of
+the top-level supervisor for the listener.
+An error tuple is returned on error. The error reason may
+be any Erlang term.
+A common error is `eaddrinuse`. It indicates that the port
+configured for Cowboy is already in use.
+== Changelog
+* *2.0*: HTTP/2 support added.
+* *2.0*: Function introduced. Replaces `cowboy:start_http/4`.
+== Examples
+.Start a listener
+Dispatch = cowboy_router:compile([
+ {'_', [
+ {"/", toppage_h, []}
+ ]}
+{ok, _} = cowboy:start_clear(example, 100, [{port, 8080}], #{
+ env => #{dispatch => Dispatch}
+.Start a listener on a random port
+Name = example,
+{ok, _} = cowboy:start_clear(Name, 100, [], #{
+ env => #{dispatch => Dispatch}
+Port = ranch:get_port(Name).
+== See also