From 4156fa3ebb978a21b52abf94202bb3d7676f4c03 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Thu, 12 Apr 2012 23:22:52 +0200 Subject: Import the acceptor code from Cowboy Modules were renamed. The 'cowboy_' prefix became 'ranch_'. At the same time, ranch_ssl_transport became ranch_ssl, and ranch_tcp_transport became ranch_tcp, because appending '_transport' felt a bit redundant considering SSL and TCP clearly are transports. One test has been added to make sure everything is working. --- src/ranch.erl | 114 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 114 insertions(+) create mode 100644 src/ranch.erl (limited to 'src/ranch.erl') diff --git a/src/ranch.erl b/src/ranch.erl new file mode 100644 index 0000000..ab9d767 --- /dev/null +++ b/src/ranch.erl @@ -0,0 +1,114 @@ +%% Copyright (c) 2011-2012, Loïc Hoguin +%% +%% Permission to use, copy, modify, and/or distribute this software for any +%% purpose with or without fee is hereby granted, provided that the above +%% copyright notice and this permission notice appear in all copies. +%% +%% THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +%% WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +%% MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +%% ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +%% WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +%% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +%% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +%% @doc Ranch API to start and stop listeners. +-module(ranch). + +-export([start_listener/6, stop_listener/1, child_spec/6, accept_ack/1, + get_protocol_options/1, set_protocol_options/2]). + +%% @doc Start a listener for the given transport and protocol. +%% +%% A listener is effectively a pool of NbAcceptors acceptors. +%% Acceptors accept connections on the given Transport and forward +%% connections to the given Protocol handler. Both transport and +%% protocol modules can be given options through the TransOpts and +%% the ProtoOpts arguments. Available options are documented in the +%% listen transport function and in the protocol module of your choice. +%% +%% All acceptor and connection 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. +%% +%% The Transport option max_connections allows you to define +%% the maximum number of simultaneous connections for this listener. It defaults +%% to 1024. See ranch_listener for more details on limiting the number +%% of connections. +%% +%% Ref 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) + when is_integer(NbAcceptors) andalso is_atom(Transport) + andalso is_atom(Protocol) -> + supervisor:start_child(ranch_sup, child_spec(Ref, NbAcceptors, + Transport, TransOpts, Protocol, ProtoOpts)). + +%% @doc Stop a listener identified by Ref. +%% +%% Note that stopping the listener will close all currently running +%% connections abruptly. +-spec stop_listener(any()) -> ok | {error, not_found}. +stop_listener(Ref) -> + case supervisor:terminate_child(ranch_sup, {ranch_listener_sup, Ref}) of + ok -> + supervisor:delete_child(ranch_sup, {ranch_listener_sup, Ref}); + {error, Reason} -> + {error, Reason} + end. + +%% @doc Return a child spec suitable for embedding. +%% +%% When you want to embed Ranch in another application, you can use this +%% function to create a ChildSpec suitable for use in a supervisor. +%% The parameters are the same as in start_listener/6 but rather +%% than hooking the listener to the Ranch internal supervisor, it just returns +%% the spec. +-spec child_spec(any(), non_neg_integer(), module(), any(), module(), any()) + -> supervisor:child_spec(). +child_spec(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts) + when is_integer(NbAcceptors) andalso is_atom(Transport) + andalso is_atom(Protocol) -> + {{ranch_listener_sup, Ref}, {ranch_listener_sup, start_link, [ + NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts + ]}, permanent, 5000, supervisor, [ranch_listener_sup]}. + +%% @doc Acknowledge the accepted connection. +%% +%% Effectively used to make sure the socket control has been given to +%% the protocol process before starting to use it. +-spec accept_ack(pid()) -> ok. +accept_ack(ListenerPid) -> + receive {shoot, ListenerPid} -> ok end. + +%% @doc Return the current protocol options for the given listener. +-spec get_protocol_options(any()) -> any(). +get_protocol_options(Ref) -> + ListenerPid = ref_to_listener_pid(Ref), + {ok, ProtoOpts} = ranch_listener:get_protocol_options(ListenerPid), + ProtoOpts. + +%% @doc Upgrade the protocol options for the given listener. +%% +%% The upgrade takes place at the acceptor level, meaning that only the +%% newly accepted connections receive the new protocol options. This has +%% no effect on the currently opened connections. +-spec set_protocol_options(any(), any()) -> ok. +set_protocol_options(Ref, ProtoOpts) -> + ListenerPid = ref_to_listener_pid(Ref), + ok = ranch_listener:set_protocol_options(ListenerPid, ProtoOpts). + +%% Internal. + +-spec ref_to_listener_pid(any()) -> pid(). +ref_to_listener_pid(Ref) -> + Children = supervisor:which_children(ranch_sup), + {_, ListenerSupPid, _, _} = lists:keyfind( + {ranch_listener_sup, Ref}, 1, Children), + ListenerSupChildren = supervisor:which_children(ListenerSupPid), + {_, ListenerPid, _, _} = lists:keyfind( + ranch_listener, 1, ListenerSupChildren), + ListenerPid. -- cgit v1.2.3