From 20a48ce65e0f14898e5027df080ec01813c1feb0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Sat, 7 Dec 2013 15:28:02 +0100 Subject: Get rid of a ton of pointless comments All of it can be found in the manual, which defines what the code must do, and is always up to date unlike the code comments. --- src/ranch.app.src | 2 +- src/ranch.erl | 63 +----------------------- src/ranch_acceptor.erl | 10 +--- src/ranch_acceptors_sup.erl | 10 +--- src/ranch_app.erl | 11 +---- src/ranch_conns_sup.erl | 4 +- src/ranch_listener_sup.erl | 10 +--- src/ranch_protocol.erl | 3 +- src/ranch_server.erl | 21 +------- src/ranch_ssl.erl | 116 +------------------------------------------- src/ranch_sup.erl | 14 +----- src/ranch_tcp.erl | 70 ++------------------------ src/ranch_transport.erl | 56 +-------------------- 13 files changed, 18 insertions(+), 372 deletions(-) diff --git a/src/ranch.app.src b/src/ranch.app.src index bb6db94..71aba15 100644 --- a/src/ranch.app.src +++ b/src/ranch.app.src @@ -1,4 +1,4 @@ -%% Copyright (c) 2011-2012, Loïc Hoguin +%% Copyright (c) 2011-2013, 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 diff --git a/src/ranch.erl b/src/ranch.erl index 641fc4d..17d24d2 100644 --- a/src/ranch.erl +++ b/src/ranch.erl @@ -1,4 +1,4 @@ -%% Copyright (c) 2011-2012, Loïc Hoguin +%% Copyright (c) 2011-2013, 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 @@ -12,7 +12,6 @@ %% 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]). @@ -35,30 +34,6 @@ -type ref() :: any(). -export_type([ref/0]). -%% @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. -%% -%% This function will return `{error, badarg}` if and only if the transport -%% module given doesn't appear to be correct. -spec start_listener(ref(), non_neg_integer(), module(), any(), module(), any()) -> {ok, pid()} | {error, badarg}. start_listener(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts) @@ -92,10 +67,6 @@ start_listener(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts) Res end. -%% @doc Stop a listener identified by Ref. -%% -%% Note that stopping the listener will close all currently running -%% connections abruptly. -spec stop_listener(ref()) -> ok | {error, not_found}. stop_listener(Ref) -> case supervisor:terminate_child(ranch_sup, {ranch_listener_sup, Ref}) of @@ -106,13 +77,6 @@ stop_listener(Ref) -> {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(ref(), non_neg_integer(), module(), any(), module(), any()) -> supervisor:child_spec(). child_spec(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts) @@ -122,61 +86,38 @@ child_spec(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts) Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts ]}, permanent, infinity, 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(ref()) -> ok. accept_ack(Ref) -> receive {shoot, Ref, Transport, Socket, AckTimeout} -> Transport:accept_ack(Socket, AckTimeout) end. -%% @doc Remove the calling process' connection from the pool. -%% -%% Useful if you have long-lived connections that aren't taking up -%% resources and shouldn't be counted in the limited number of running -%% connections. -spec remove_connection(ref()) -> ok. remove_connection(Ref) -> ConnsSup = ranch_server:get_connections_sup(Ref), ConnsSup ! {remove_connection, Ref}, ok. -%% @doc Return the listener's port. -spec get_port(ref()) -> inet:port_number(). get_port(Ref) -> ranch_server:get_port(Ref). -%% @doc Return the max number of connections allowed concurrently. -spec get_max_connections(ref()) -> max_conns(). get_max_connections(Ref) -> ranch_server:get_max_connections(Ref). -%% @doc Set the max number of connections allowed concurrently. -spec set_max_connections(ref(), max_conns()) -> ok. set_max_connections(Ref, MaxConnections) -> ranch_server:set_max_connections(Ref, MaxConnections). -%% @doc Return the current protocol options for the given listener. -spec get_protocol_options(ref()) -> any(). get_protocol_options(Ref) -> ranch_server:get_protocol_options(Ref). -%% @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(ref(), any()) -> ok. set_protocol_options(Ref, Opts) -> ranch_server:set_protocol_options(Ref, Opts). -%% @doc Filter a list of options and remove all unwanted values. -%% -%% It takes a list of options, a list of allowed keys and an accumulator. -%% This accumulator can be used to set default options that should never -%% be overriden. -spec filter_options([{atom(), any()} | {raw, any(), any(), any()}], [atom()], Acc) -> Acc when Acc :: [any()]. filter_options([], _, Acc) -> @@ -192,7 +133,6 @@ filter_options([Opt = {raw, _, _, _}|Tail], AllowedKeys, Acc) -> false -> filter_options(Tail, AllowedKeys, Acc) end. -%% @doc Add an option to a list, but only if it wasn't previously set. -spec set_option_default(Opts, atom(), any()) -> Opts when Opts :: [{atom(), any()}]. set_option_default(Opts, Key, Value) -> @@ -201,7 +141,6 @@ set_option_default(Opts, Key, Value) -> false -> [{Key, Value}|Opts] end. -%% @doc Start the given applications if they were not already started. -spec require([atom()]) -> ok. require([]) -> ok; diff --git a/src/ranch_acceptor.erl b/src/ranch_acceptor.erl index da1aac5..5400b7b 100644 --- a/src/ranch_acceptor.erl +++ b/src/ranch_acceptor.erl @@ -1,4 +1,4 @@ -%% Copyright (c) 2011-2012, Loïc Hoguin +%% Copyright (c) 2011-2013, 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 @@ -12,25 +12,17 @@ %% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF %% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -%% @private -module(ranch_acceptor). -%% API. -export([start_link/3]). - -%% Internal. -export([loop/3]). -%% API. - -spec start_link(inet:socket(), module(), pid()) -> {ok, pid()}. start_link(LSocket, Transport, ConnsSup) -> Pid = spawn_link(?MODULE, loop, [LSocket, Transport, ConnsSup]), {ok, Pid}. -%% Internal. - -spec loop(inet:socket(), module(), pid()) -> no_return(). loop(LSocket, Transport, ConnsSup) -> _ = case Transport:accept(LSocket, infinity) of diff --git a/src/ranch_acceptors_sup.erl b/src/ranch_acceptors_sup.erl index d8f8ba1..463db9b 100644 --- a/src/ranch_acceptors_sup.erl +++ b/src/ranch_acceptors_sup.erl @@ -1,4 +1,4 @@ -%% Copyright (c) 2011-2012, Loïc Hoguin +%% Copyright (c) 2011-2013, 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 @@ -12,25 +12,17 @@ %% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF %% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -%% @private -module(ranch_acceptors_sup). -behaviour(supervisor). -%% API. -export([start_link/4]). - -%% supervisor. -export([init/1]). -%% API. - -spec start_link(ranch:ref(), non_neg_integer(), module(), any()) -> {ok, pid()}. start_link(Ref, NbAcceptors, Transport, TransOpts) -> supervisor:start_link(?MODULE, [Ref, NbAcceptors, Transport, TransOpts]). -%% supervisor. - init([Ref, NbAcceptors, Transport, TransOpts]) -> ConnsSup = ranch_server:get_connections_sup(Ref), LSocket = case proplists:get_value(socket, TransOpts) of diff --git a/src/ranch_app.erl b/src/ranch_app.erl index 2402de6..95c9031 100644 --- a/src/ranch_app.erl +++ b/src/ranch_app.erl @@ -1,4 +1,4 @@ -%% Copyright (c) 2011-2012, Loïc Hoguin +%% Copyright (c) 2011-2013, 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 @@ -12,19 +12,15 @@ %% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF %% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -%% @private -module(ranch_app). -behaviour(application). -%% API. -export([start/2]). -export([stop/1]). -export([profile_output/0]). -%% API. - start(_, _) -> - consider_profiling(), + _ = consider_profiling(), ranch_sup:start_link(). stop(_) -> @@ -38,9 +34,6 @@ profile_output() -> eprof:log("total.profile"), eprof:analyze(total). -%% Internal. - --spec consider_profiling() -> profiling | not_profiling. consider_profiling() -> case application:get_env(profile) of {ok, true} -> diff --git a/src/ranch_conns_sup.erl b/src/ranch_conns_sup.erl index 308a1ab..08748d0 100644 --- a/src/ranch_conns_sup.erl +++ b/src/ranch_conns_sup.erl @@ -1,4 +1,4 @@ -%% Copyright (c) 2011-2012, Loïc Hoguin +%% Copyright (c) 2011-2013, 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 @@ -12,8 +12,6 @@ %% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF %% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -%% @private -%% %% Make sure to never reload this module outside a release upgrade, %% as calling l(ranch_conns_sup) twice will kill the process and all %% the currently open connections. diff --git a/src/ranch_listener_sup.erl b/src/ranch_listener_sup.erl index 30017d0..6fb2898 100644 --- a/src/ranch_listener_sup.erl +++ b/src/ranch_listener_sup.erl @@ -1,4 +1,4 @@ -%% Copyright (c) 2011-2012, Loïc Hoguin +%% Copyright (c) 2011-2013, 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 @@ -12,18 +12,12 @@ %% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF %% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -%% @private -module(ranch_listener_sup). -behaviour(supervisor). -%% API. -export([start_link/6]). - -%% supervisor. -export([init/1]). -%% API. - -spec start_link(ranch:ref(), non_neg_integer(), module(), any(), module(), any()) -> {ok, pid()}. start_link(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts) -> @@ -33,8 +27,6 @@ start_link(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts) -> Ref, NbAcceptors, Transport, TransOpts, Protocol }). -%% supervisor. - init({Ref, NbAcceptors, Transport, TransOpts, Protocol}) -> AckTimeout = proplists:get_value(ack_timeout, TransOpts, 5000), ConnType = proplists:get_value(connection_type, TransOpts, worker), diff --git a/src/ranch_protocol.erl b/src/ranch_protocol.erl index c179789..683acfc 100644 --- a/src/ranch_protocol.erl +++ b/src/ranch_protocol.erl @@ -1,4 +1,4 @@ -%% Copyright (c) 2012, Loïc Hoguin +%% Copyright (c) 2012-2013, 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 @@ -12,7 +12,6 @@ %% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF %% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -%% @private -module(ranch_protocol). %% Start a new connection process for the given socket. diff --git a/src/ranch_server.erl b/src/ranch_server.erl index 0b21cce..2e74248 100644 --- a/src/ranch_server.erl +++ b/src/ranch_server.erl @@ -1,4 +1,4 @@ -%% Copyright (c) 2012, Loïc Hoguin +%% Copyright (c) 2012-2013, 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 @@ -12,7 +12,6 @@ %% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF %% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -%% @private -module(ranch_server). -behaviour(gen_server). @@ -47,17 +46,14 @@ %% API. -%% @doc Start the ranch_server gen_server. -spec start_link() -> {ok, pid()}. start_link() -> gen_server:start_link({local, ?MODULE}, ?MODULE, [], []). -%% @private -spec set_new_listener_opts(ranch:ref(), ranch:max_conns(), any()) -> ok. set_new_listener_opts(Ref, MaxConns, Opts) -> gen_server:call(?MODULE, {set_new_listener_opts, Ref, MaxConns, Opts}). -%% @doc Cleanup listener options after it has been stopped. -spec cleanup_listener_opts(ranch:ref()) -> ok. cleanup_listener_opts(Ref) -> _ = ets:delete(?TAB, {port, Ref}), @@ -65,61 +61,50 @@ cleanup_listener_opts(Ref) -> _ = ets:delete(?TAB, {opts, Ref}), ok. -%% @doc Set a connection supervisor associated with specific listener. -spec set_connections_sup(ranch:ref(), pid()) -> ok. set_connections_sup(Ref, Pid) -> true = gen_server:call(?MODULE, {set_connections_sup, Ref, Pid}), ok. -%% @doc Return the connection supervisor used by specific listener. -spec get_connections_sup(ranch:ref()) -> pid(). get_connections_sup(Ref) -> ets:lookup_element(?TAB, {conns_sup, Ref}, 2). -%% @private -spec set_port(ranch:ref(), inet:port_number()) -> ok. set_port(Ref, Port) -> gen_server:call(?MODULE, {set_port, Ref, Port}). -%% @doc Return the listener's port. -spec get_port(ranch:ref()) -> inet:port_number(). get_port(Ref) -> ets:lookup_element(?TAB, {port, Ref}, 2). -%% @doc Set the max number of connections allowed concurrently. -spec set_max_connections(ranch:ref(), ranch:max_conns()) -> ok. set_max_connections(Ref, MaxConnections) -> gen_server:call(?MODULE, {set_max_conns, Ref, MaxConnections}). -%% @doc Return the max number of connections allowed concurrently. -spec get_max_connections(ranch:ref()) -> ranch:max_conns(). get_max_connections(Ref) -> ets:lookup_element(?TAB, {max_conns, Ref}, 2). -%% @doc Upgrade the protocol options. -spec set_protocol_options(ranch:ref(), any()) -> ok. set_protocol_options(Ref, ProtoOpts) -> gen_server:call(?MODULE, {set_opts, Ref, ProtoOpts}). -%% @doc Return the current protocol options. -spec get_protocol_options(ranch:ref()) -> any(). get_protocol_options(Ref) -> ets:lookup_element(?TAB, {opts, Ref}, 2). -%% @doc Count the number of connections in the connection pool. -spec count_connections(ranch:ref()) -> non_neg_integer(). count_connections(Ref) -> ranch_conns_sup:active_connections(get_connections_sup(Ref)). %% gen_server. -%% @private init([]) -> Monitors = [{{erlang:monitor(process, Pid), Pid}, Ref} || [Ref, Pid] <- ets:match(?TAB, {{conns_sup, '$1'}, '$2'})], {ok, #state{monitors=Monitors}}. -%% @private handle_call({set_new_listener_opts, Ref, MaxConns, Opts}, _, State) -> ets:insert(?TAB, {{max_conns, Ref}, MaxConns}), ets:insert(?TAB, {{opts, Ref}, Opts}), @@ -150,11 +135,9 @@ handle_call({set_opts, Ref, Opts}, _, State) -> handle_call(_Request, _From, State) -> {reply, ignore, State}. -%% @private handle_cast(_Request, State) -> {noreply, State}. -%% @private handle_info({'DOWN', MonitorRef, process, Pid, _}, State=#state{monitors=Monitors}) -> {_, Ref} = lists:keyfind({MonitorRef, Pid}, 1, Monitors), @@ -164,10 +147,8 @@ handle_info({'DOWN', MonitorRef, process, Pid, _}, handle_info(_Info, State) -> {noreply, State}. -%% @private terminate(_Reason, _State) -> ok. -%% @private code_change(_OldVsn, State, _Extra) -> {ok, State}. diff --git a/src/ranch_ssl.erl b/src/ranch_ssl.erl index 31950e9..3f73655 100644 --- a/src/ranch_ssl.erl +++ b/src/ranch_ssl.erl @@ -1,4 +1,4 @@ -%% Copyright (c) 2011-2012, Loïc Hoguin +%% Copyright (c) 2011-2013, 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 @@ -12,17 +12,6 @@ %% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF %% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -%% @doc SSL transport API. -%% -%% Wrapper around ssl implementing the Ranch transport API. -%% -%% This transport requires the crypto, asn1, -%% public_key and ssl applications to be started. -%% If they aren't started, it will try to start them itself before -%% opening a port to listen. Applications aren't stopped when the -%% listening socket is closed, though. -%% -%% @see ssl -module(ranch_ssl). -behaviour(ranch_transport). @@ -71,77 +60,10 @@ | {verify_fun, {fun(), InitialUserState::term()}}]. -export_type([opts/0]). -%% @doc Name of this transport, ssl. name() -> ssl. -%% @doc Atoms used to identify messages in {active, once | true} mode. messages() -> {ssl, ssl_closed, ssl_error}. -%% @doc Listen for connections on the given port number. -%% -%% Calling this function returns a listening socket that can then -%% The available options are: -%% -%%
-%%
backlog
Maximum length of the pending connections queue. -%% Defaults to 1024.
-%%
cacertfile
Optional. Path to file containing PEM encoded -%% CA certificates (trusted certificates used for verifying a peer -%% certificate).
-%%
cert
Optional. The DER encoded users certificate. If this -%% option is supplied it will override the certfile option.
-%%
certfile
Mandatory. Path to a file containing the user's -%% certificate.
-%%
ciphers
Optional. The cipher suites that should be supported. -%% The function ssl:cipher_suites/0 can be used to find all available -%% ciphers.
-%%
fail_if_no_peer_cert
Optional. Used together with {verify, verify_peer}. -%% If set to true, the server will fail if the client does not have a certificate -%% to send, i.e. sends a empty certificate, if set to false (that is by default) -%% it will only fail if the client sends an invalid certificate (an empty -%% certificate is considered valid).
-%%
hibernate_after
When an integer-value is specified, the ssl_connection -%% will go into hibernation after the specified number of milliseconds of inactivity, -%% thus reducing its memory footprint. When undefined is specified (this is the -%% default), the process will never go into hibernation.
-%%
ip
Interface to listen on. Listen on all interfaces -%% by default.
-%%
key
Optional. The DER encoded users private key. If this option -%% is supplied it will override the keyfile option.
-%%
keyfile
Optional. Path to the file containing the user's -%% private PEM encoded key.
-%%
next_protocols_advertised
Optional. Erlang R16B+ required. -%% List of protocols advertised by TLS Next Protocol Negotiation -%% extension.
-%%
nodelay
Optional. Enable TCP_NODELAY. Enabled by default.
-%%
password
Optional. String containing the user's password. -%% All private keyfiles must be password protected currently.
-%%
port
TCP port number to open. Defaults to 0 (see below)
-%%
reuse_session
Optional. Enables the ssl server to have a local -%% policy for deciding if a session should be reused or not, only meaningful -%% if reuse_sessions is set to true.
-%%
reuse_sessions
Optional. Specifies if the server should agree -%% to reuse sessions when the clients request to do so.
-%%
secure_renegotiate
Optional. Specifies if to reject renegotiation -%% attempt that does not live up to RFC 5746. By default secure_renegotiate is -%% set to false i.e. secure renegotiation will be used if possible but it will -%% fallback to unsecure renegotiation if the peer does not support RFC 5746.
-%%
verify
Optional. If set to verify_peer, performs an x509-path -%% validation and request the client for a certificate.
-%%
verify_fun
Optional. The verify fun will be called during the -%% X509-path validation when an error or an extension unknown to the ssl -%% application is encountered. Additionally it will be called when a certificate -%% is considered valid by the path validation to allow access to each certificate -%% in the path to the user application.
-%%
-%% -%% You can listen to a random port by setting the port option to 0. -%% It is then possible to retrieve this port number by calling -%% sockname/1 on the listening socket. If you are using Ranch's -%% listener API, then this port number can obtained through -%% ranch:get_port/1 instead. -%% -%% @see ssl:listen/2 -spec listen(opts()) -> {ok, ssl:sslsocket()} | {error, atom()}. listen(Opts) -> ranch:require([crypto, asn1, public_key, ssl]), @@ -163,13 +85,6 @@ listen(Opts) -> [binary, {active, false}, {packet, raw}, {reuseaddr, true}, {nodelay, true}])). -%% @doc Accept connections with the given listening socket. -%% -%% Note that this function does both the transport accept and -%% the SSL handshake. The returned socket is thus fully connected. -%% -%% @see ssl:transport_accept/2 -%% @see ssl:ssl_accept/2 -spec accept(ssl:sslsocket(), timeout()) -> {ok, ssl:sslsocket()} | {error, closed | timeout | atom()}. accept(LSocket, Timeout) -> @@ -185,8 +100,6 @@ accept_ack(CSocket, Timeout) -> error(Reason) end. -%% @private Experimental. Open a connection to the given host and port number. -%% @see ssl:connect/3 %% @todo Probably filter Opts? -spec connect(inet:ip_address() | inet:hostname(), inet:port_number(), any()) @@ -195,8 +108,6 @@ connect(Host, Port, Opts) when is_integer(Port) -> ssl:connect(Host, Port, Opts ++ [binary, {active, false}, {packet, raw}]). -%% @private Experimental. Open a connection to the given host and port number. -%% @see ssl:connect/4 %% @todo Probably filter Opts? -spec connect(inet:ip_address() | inet:hostname(), inet:port_number(), any(), timeout()) @@ -206,80 +117,55 @@ connect(Host, Port, Opts, Timeout) when is_integer(Port) -> Opts ++ [binary, {active, false}, {packet, raw}], Timeout). -%% @doc Receive data from a socket in passive mode. -%% @see ssl:recv/3 -spec recv(ssl:sslsocket(), non_neg_integer(), timeout()) -> {ok, any()} | {error, closed | atom()}. recv(Socket, Length, Timeout) -> ssl:recv(Socket, Length, Timeout). -%% @doc Send data on a socket. -%% @see ssl:send/2 -spec send(ssl:sslsocket(), iodata()) -> ok | {error, atom()}. send(Socket, Packet) -> ssl:send(Socket, Packet). -%% @equiv sendfile(Socket, Filename, 0, 0, []) -spec sendfile(ssl:sslsocket(), file:name_all() | file:fd()) -> {ok, non_neg_integer()} | {error, atom()}. sendfile(Socket, Filename) -> sendfile(Socket, Filename, 0, 0, []). -%% @equiv sendfile(Socket, File, Offset, Bytes, []) -spec sendfile(ssl:sslsocket(), file:name_all() | file:fd(), non_neg_integer(), non_neg_integer()) -> {ok, non_neg_integer()} | {error, atom()}. sendfile(Socket, File, Offset, Bytes) -> sendfile(Socket, File, Offset, Bytes, []). -%% @doc Send part of a file on a socket. -%% %% Unlike with TCP, no syscall can be used here, so sending files %% through SSL will be much slower in comparison. Note that unlike %% file:sendfile/5 this function accepts either a file or a file name. -%% -%% @see ranch_transport:sendfile/6 -%% @see file:sendfile/5 -spec sendfile(ssl:sslsocket(), file:name_all() | file:fd(), non_neg_integer(), non_neg_integer(), ranch_transport:sendfile_opts()) -> {ok, non_neg_integer()} | {error, atom()}. sendfile(Socket, File, Offset, Bytes, Opts) -> ranch_transport:sendfile(?MODULE, Socket, File, Offset, Bytes, Opts). -%% @doc Set options on the given socket. -%% @see ssl:setopts/2 %% @todo Probably filter Opts? -spec setopts(ssl:sslsocket(), list()) -> ok | {error, atom()}. setopts(Socket, Opts) -> ssl:setopts(Socket, Opts). -%% @doc Give control of the socket to a new process. -%% -%% Must be called from the process currently controlling the socket, -%% otherwise an {error, not_owner} tuple will be returned. -%% -%% @see ssl:controlling_process/2 -spec controlling_process(ssl:sslsocket(), pid()) -> ok | {error, closed | not_owner | atom()}. controlling_process(Socket, Pid) -> ssl:controlling_process(Socket, Pid). -%% @doc Return the remote address and port of the connection. -%% @see ssl:peername/1 -spec peername(ssl:sslsocket()) -> {ok, {inet:ip_address(), inet:port_number()}} | {error, atom()}. peername(Socket) -> ssl:peername(Socket). -%% @doc Return the local address and port of the connection. -%% @see ssl:sockname/1 -spec sockname(ssl:sslsocket()) -> {ok, {inet:ip_address(), inet:port_number()}} | {error, atom()}. sockname(Socket) -> ssl:sockname(Socket). -%% @doc Close the given socket. -%% @see ssl:close/1 -spec close(ssl:sslsocket()) -> ok. close(Socket) -> ssl:close(Socket). diff --git a/src/ranch_sup.erl b/src/ranch_sup.erl index ddf2f69..80c0665 100644 --- a/src/ranch_sup.erl +++ b/src/ranch_sup.erl @@ -1,4 +1,4 @@ -%% Copyright (c) 2011-2012, Loïc Hoguin +%% Copyright (c) 2011-2013, 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 @@ -12,25 +12,15 @@ %% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF %% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -%% @private -module(ranch_sup). -behaviour(supervisor). -%% API. -export([start_link/0]). - -%% supervisor. -export([init/1]). --define(SUPERVISOR, ?MODULE). - -%% API. - -spec start_link() -> {ok, pid()}. start_link() -> - supervisor:start_link({local, ?SUPERVISOR}, ?MODULE, []). - -%% supervisor. + supervisor:start_link({local, ?MODULE}, ?MODULE, []). init([]) -> ranch_server = ets:new(ranch_server, [ diff --git a/src/ranch_tcp.erl b/src/ranch_tcp.erl index 27ecb3e..bd2eea6 100644 --- a/src/ranch_tcp.erl +++ b/src/ranch_tcp.erl @@ -1,4 +1,4 @@ -%% Copyright (c) 2011-2012, Loïc Hoguin +%% Copyright (c) 2011-2013, 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 @@ -12,11 +12,6 @@ %% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF %% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -%% @doc TCP transport API. -%% -%% Wrapper around gen_tcp implementing the Ranch transport API. -%% -%% @see gen_tcp -module(ranch_tcp). -behaviour(ranch_transport). @@ -49,34 +44,10 @@ | {send_timeout_close, boolean()}]. -export_type([opts/0]). -%% @doc Name of this transport, tcp. name() -> tcp. -%% @doc Atoms used to identify messages in {active, once | true} mode. messages() -> {tcp, tcp_closed, tcp_error}. -%% @doc Listen for connections on the given port number. -%% -%% Calling this function returns a listening socket that can then -%% be passed to accept/2 to accept connections. -%% -%% The available options are: -%%
-%%
backlog
Maximum length of the pending connections queue. -%% Defaults to 1024.
-%%
ip
Interface to listen on. Listen on all interfaces -%% by default.
-%%
nodelay
Optional. Enable TCP_NODELAY. Enabled by default.
-%%
port
TCP port number to open. Defaults to 0 (see below).
-%%
-%% -%% You can listen to a random port by setting the port option to 0. -%% It is then possible to retrieve this port number by calling -%% sockname/1 on the listening socket. If you are using Ranch's -%% listener API, then this port number can obtained through -%% ranch:get_port/1 instead. -%% -%% @see gen_tcp:listen/2 -spec listen(opts()) -> {ok, inet:socket()} | {error, atom()}. listen(Opts) -> Opts2 = ranch:set_option_default(Opts, backlog, 1024), @@ -91,8 +62,6 @@ listen(Opts) -> [binary, {active, false}, {packet, raw}, {reuseaddr, true}, {nodelay, true}])). -%% @doc Accept connections with the given listening socket. -%% @see gen_tcp:accept/2 -spec accept(inet:socket(), timeout()) -> {ok, inet:socket()} | {error, closed | timeout | atom()}. accept(LSocket, Timeout) -> @@ -102,8 +71,6 @@ accept(LSocket, Timeout) -> accept_ack(_, _) -> ok. -%% @private Experimental. Open a connection to the given host and port number. -%% @see gen_tcp:connect/3 %% @todo Probably filter Opts? -spec connect(inet:ip_address() | inet:hostname(), inet:port_number(), any()) @@ -112,9 +79,6 @@ connect(Host, Port, Opts) when is_integer(Port) -> gen_tcp:connect(Host, Port, Opts ++ [binary, {active, false}, {packet, raw}]). -%% @private Experimental. Open a connection to the given host and port -%% number with a timeout. -%% @see gen_tcp:connect/4 %% @todo Probably filter Opts? -spec connect(inet:ip_address() | inet:hostname(), inet:port_number(), any(), timeout()) @@ -124,39 +88,26 @@ connect(Host, Port, Opts, Timeout) when is_integer(Port) -> Opts ++ [binary, {active, false}, {packet, raw}], Timeout). -%% @doc Receive data from a socket in passive mode. -%% @see gen_tcp:recv/3 -spec recv(inet:socket(), non_neg_integer(), timeout()) -> {ok, any()} | {error, closed | atom()}. recv(Socket, Length, Timeout) -> gen_tcp:recv(Socket, Length, Timeout). -%% @doc Send data on a socket. -%% @see gen_tcp:send/2 -spec send(inet:socket(), iodata()) -> ok | {error, atom()}. send(Socket, Packet) -> gen_tcp:send(Socket, Packet). -%% @equiv sendfile(Socket, File, Offset, Bytes, []) -spec sendfile(inet:socket(), file:name_all() | file:fd()) -> {ok, non_neg_integer()} | {error, atom()}. sendfile(Socket, Filename) -> sendfile(Socket, Filename, 0, 0, []). -%% @equiv sendfile(Socket, File, Offset, Bytes, []) -spec sendfile(inet:socket(), file:name_all() | file:fd(), non_neg_integer(), non_neg_integer()) -> {ok, non_neg_integer()} | {error, atom()}. sendfile(Socket, File, Offset, Bytes) -> sendfile(Socket, File, Offset, Bytes, []). -%% @doc Send part of a file on a socket. -%% -%% As with sendfile/2 this is the optimal way to send (parts) of files using -%% TCP. Note that unlike file:sendfile/5 this function accepts either a raw file -%% or a file name and the ordering of arguments is different. -%% -%% @see file:sendfile/5 -spec sendfile(inet:socket(), file:name_all() | file:fd(), non_neg_integer(), non_neg_integer(), [{chunk_size, non_neg_integer()}]) -> {ok, non_neg_integer()} | {error, atom()}. @@ -182,46 +133,33 @@ sendfile(Socket, RawFile, Offset, Bytes, Opts) -> Result -> Result catch error:{badmatch, {error, enotconn}} -> - %% file:sendfile/5 might fail by throwing a {badmatch, {error, enotconn}} - %% this is because its internal implementation fails with a badmatch in + %% file:sendfile/5 might fail by throwing a + %% {badmatch, {error, enotconn}}. This is because its + %% implementation fails with a badmatch in %% prim_file:sendfile/10 if the socket is not connected. {error, closed} end. -%% @doc Set options on the given socket. -%% @see inet:setopts/2 %% @todo Probably filter Opts? -spec setopts(inet:socket(), list()) -> ok | {error, atom()}. setopts(Socket, Opts) -> inet:setopts(Socket, Opts). -%% @doc Give control of the socket to a new process. -%% -%% Must be called from the process currently controlling the socket, -%% otherwise an {error, not_owner} tuple will be returned. -%% -%% @see gen_tcp:controlling_process/2 -spec controlling_process(inet:socket(), pid()) -> ok | {error, closed | not_owner | atom()}. controlling_process(Socket, Pid) -> gen_tcp:controlling_process(Socket, Pid). -%% @doc Return the remote address and port of the connection. -%% @see inet:peername/1 -spec peername(inet:socket()) -> {ok, {inet:ip_address(), inet:port_number()}} | {error, atom()}. peername(Socket) -> inet:peername(Socket). -%% @doc Return the local address and port of the connection. -%% @see inet:sockname/1 -spec sockname(inet:socket()) -> {ok, {inet:ip_address(), inet:port_number()}} | {error, atom()}. sockname(Socket) -> inet:sockname(Socket). -%% @doc Close the given socket. -%% @see gen_tcp:close/1 -spec close(inet:socket()) -> ok. close(Socket) -> gen_tcp:close(Socket). diff --git a/src/ranch_transport.erl b/src/ranch_transport.erl index 5cf10d1..33c6fad 100644 --- a/src/ranch_transport.erl +++ b/src/ranch_transport.erl @@ -1,4 +1,4 @@ -%% Copyright (c) 2012, Loïc Hoguin +%% Copyright (c) 2012-2013, 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 @@ -12,7 +12,6 @@ %% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF %% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -%% @private -module(ranch_transport). -export([sendfile/6]). @@ -22,92 +21,39 @@ -type sendfile_opts() :: [{chunk_size, non_neg_integer()}]. -export_type([sendfile_opts/0]). -%% Name of the transport. -callback name() -> atom(). - %% @todo -callback caps(secure | sendfile) -> boolean(). - -%% Atoms used to identify messages in {active, once | true} mode. -callback messages() -> {OK::atom(), Closed::atom(), Error::atom()}. - -%% Listen for connections on the given port number. -%% -%% Calling this function returns a listening socket that can then -%% be passed to accept/2 to accept connections. -%% -%% Available options may vary between transports. -%% -%% You can listen to a random port by setting the port option to 0. -%% It is then possible to retrieve this port number by calling -%% sockname/1 on the listening socket. If you are using Ranch's -%% listener API, then this port number can obtained through -%% ranch:get_port/1 instead. -callback listen(opts()) -> {ok, socket()} | {error, atom()}. - -%% Accept connections with the given listening socket. -callback accept(socket(), timeout()) -> {ok, socket()} | {error, closed | timeout | atom()}. - -%% Perform post-accept operations on the socket. -callback accept_ack(socket(), timeout()) -> ok. - -%% Experimental. Open a connection to the given host and port number. -callback connect(string(), inet:port_number(), opts()) -> {ok, socket()} | {error, atom()}. - -%% Experimental. Open a connection to the given host and port number -%% with a timeout. -callback connect(string(), inet:port_number(), opts(), timeout()) -> {ok, socket()} | {error, atom()}. - -%% Receive data from a socket in passive mode. -callback recv(socket(), non_neg_integer(), timeout()) -> {ok, any()} | {error, closed | timeout | atom()}. - -%% Send data on a socket. -callback send(socket(), iodata()) -> ok | {error, atom()}. - -%% Send a file on a socket. -callback sendfile(socket(), file:name() | file:fd()) -> {ok, non_neg_integer()} | {error, atom()}. - -%% Send part of a file on a socket. -callback sendfile(socket(), file:name() | file:fd(), non_neg_integer(), non_neg_integer()) -> {ok, non_neg_integer()} | {error, atom()}. - -%% Send part of a file on a socket. -callback sendfile(socket(), file:name() | file:fd(), non_neg_integer(), non_neg_integer(), sendfile_opts()) -> {ok, non_neg_integer()} | {error, atom()}. - -%% Set options on the given socket. -callback setopts(socket(), opts()) -> ok | {error, atom()}. - -%% Give control of the socket to a new process. -%% -%% Must be called from the process currently controlling the socket, -%% otherwise an {error, not_owner} tuple will be returned. -callback controlling_process(socket(), pid()) -> ok | {error, closed | not_owner | atom()}. - -%% Return the remote address and port of the connection. -callback peername(socket()) -> {ok, {inet:ip_address(), inet:port_number()}} | {error, atom()}. - -%% Return the local address and port of the connection. -callback sockname(socket()) -> {ok, {inet:ip_address(), inet:port_number()}} | {error, atom()}. - -%% Close the given socket. -callback close(socket()) -> ok. -%% @doc Send part of a file on a socket. -%% %% A fallback for transports that don't have a native sendfile implementation. %% Note that the ordering of arguments is different from file:sendfile/5 and %% that this function accepts either a raw file or a file name. -%% -%% @see file:sendfile/5 -spec sendfile(module(), socket(), file:filename_all() | file:fd(), non_neg_integer(), non_neg_integer(), sendfile_opts()) -> {ok, non_neg_integer()} | {error, atom()}. -- cgit v1.2.3