Module ranch

Ranch API to start and stop listeners.

Description

Ranch API to start and stop listeners.

Data Types

max_conns()

max_conns() = non_neg_integer() | infinity

Function Index

accept_ack/1Acknowledge the accepted connection.
child_spec/6Return a child spec suitable for embedding.
filter_options/3Filter a list of options and remove all unwanted values.
get_max_connections/1Return the max number of connections allowed concurrently.
get_port/1Return the listener's port.
get_protocol_options/1Return the current protocol options for the given listener.
require/1Start the given applications if they were not already started.
set_max_connections/2Set the max number of connections allowed concurrently.
set_option_default/3Add an option to a list, but only if it wasn't previously set.
set_protocol_options/2Upgrade the protocol options for the given listener.
start_listener/6Start a listener for the given transport and protocol.
stop_listener/1Stop a listener identified by Ref.

Function Details

accept_ack/1

accept_ack(ListenerPid::pid()) -> ok

Acknowledge the accepted connection.

Effectively used to make sure the socket control has been given to the protocol process before starting to use it.

child_spec/6

child_spec(Ref::any(), NbAcceptors::non_neg_integer(), Transport::module(), TransOpts::any(), Protocol::module(), ProtoOpts::any()) -> supervisor:child_spec()

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.

filter_options/3

filter_options(Tail::[{atom(), any()}], AllowedKeys::[atom()], Acc) -> Acc

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.

get_max_connections/1

get_max_connections(Ref::any()) -> max_conns()

Return the max number of connections allowed concurrently.

get_port/1

get_port(Ref::any()) -> inet:port_number()

Return the listener's port.

get_protocol_options/1

get_protocol_options(Ref::any()) -> any()

Return the current protocol options for the given listener.

require/1

require(Tail::[module()]) -> ok

Start the given applications if they were not already started.

set_max_connections/2

set_max_connections(Ref::any(), MaxConnections::max_conns()) -> ok

Set the max number of connections allowed concurrently.

set_option_default/3

set_option_default(Opts, Key::atom(), Value::any()) -> Opts

Add an option to a list, but only if it wasn't previously set.

set_protocol_options/2

set_protocol_options(Ref::any(), ProtoOpts::any()) -> ok

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.

start_listener/6

start_listener(Ref::any(), NbAcceptors::non_neg_integer(), Transport::module(), TransOpts::any(), Protocol::module(), ProtoOpts::any()) -> {ok, pid()} | {error, badarg}

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 doesnt appear to be correct.

stop_listener/1

stop_listener(Ref::any()) -> ok | {error, not_found}

Stop a listener identified by Ref.

Note that stopping the listener will close all currently running connections abruptly.


Generated by EDoc, Aug 3 2013, 11:17:12.