diff options
author | Loïc Hoguin <[email protected]> | 2011-07-06 17:42:20 +0200 |
---|---|---|
committer | Loïc Hoguin <[email protected]> | 2011-07-06 17:42:20 +0200 |
commit | 108a491f5515fdc2a7fe3ce8c310a261d6be3230 (patch) | |
tree | 74fb2109c6b193c382a0712a053702b3ec240a13 /src/cowboy.erl | |
parent | 2b3bfdd783915b263ed3fdfd6e135b9a84982821 (diff) | |
download | cowboy-108a491f5515fdc2a7fe3ce8c310a261d6be3230.tar.gz cowboy-108a491f5515fdc2a7fe3ce8c310a261d6be3230.tar.bz2 cowboy-108a491f5515fdc2a7fe3ce8c310a261d6be3230.zip |
Add documentation for the public interface.
This is probably not perfect yet but it should be better than
nothing. We'll improve things with feedback received from the
many users.
Diffstat (limited to 'src/cowboy.erl')
-rw-r--r-- | src/cowboy.erl | 25 |
1 files changed, 23 insertions, 2 deletions
diff --git a/src/cowboy.erl b/src/cowboy.erl index a1e8063..dbc64d0 100644 --- a/src/cowboy.erl +++ b/src/cowboy.erl @@ -12,11 +12,30 @@ %% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF %% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +%% @doc Cowboy API to start and stop listeners. -module(cowboy). --export([start_listener/6, stop_listener/1]). %% API. -%% API. +-export([start_listener/6, stop_listener/1]). +%% @doc Start a listener for the given transport and protocol. +%% +%% A listener is effectively a pool of <em>NbAcceptors</em> acceptors. +%% Acceptors accept connections on the given <em>Transport</em> and forward +%% requests to the given <em>Protocol</em> handler. Both transport and protocol +%% modules can be given options through the <em>TransOpts</em> and the +%% <em>ProtoOpts</em> arguments. Available options are documented in the +%% <em>listen</em> transport function and in the protocol module of your choice. +%% +%% All acceptor and request processes are supervised by the listener. +%% +%% It is recommended to set a large enough number of acceptors to improve +%% performance. The exact number depends of course on your hardware, on the +%% protocol used and on the number of expected simultaneous connections. +%% +%% Although Cowboy includes a <em>cowboy_http_protocol</em> handler, other +%% handlers can be created for different protocols like IRC, FTP and more. +%% +%% <em>Ref</em> can be used to stop the listener later on. -spec start_listener(any(), non_neg_integer(), module(), any(), module(), any()) -> {ok, pid()}. start_listener(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts) -> @@ -26,6 +45,8 @@ start_listener(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts) -> ]}, permanent, 5000, supervisor, [cowboy_listener_sup]}). +%% @doc Stop a listener identified by <em>Ref</em>. +%% @todo Currently request processes aren't terminated with the listener. -spec stop_listener(any()) -> ok | {error, not_found}. stop_listener(Ref) -> case supervisor:terminate_child(cowboy_sup, {cowboy_listener_sup, Ref}) of |