acceptor_pool behaviour (partisan v5.0.3)

This module provides a gen_tcp acceptor pool supervisor. An acceptor_pool must define the acceptor_pool behaviour callback, which is very similar to the supervisor behaviour except all children must be acceptor proccesses and only the map terms are supported. The only callback is init/1:

 -callback init(Args) -> {ok, {PoolFlags, [AcceptorSpec, ...]}} | ignore when
     Args :: any(),
     PoolFlags :: pool_flags(),
     AcceptorSpec :: acceptor_spec().

The pool_flags() are the intensity and period pairs as in as supervisor:sup_flags/0 and have the equivalent behaviour.

There must be list of a single acceptor_spec(), just as there can only be a single supervisor:child_spec/0 when the strategy is simple_one_for_one. The map pairs are the same as supervisor:child_spec/0 except that start's value is of form:

  {AcceptorMod :: module(), AcceptorArg :: term(), Opts :: [acceptor:option()]}

AcceptorMod is an acceptor callback module that will be called with argument AcceptorArg, and spawned with acceptor options Opts.

There is an additional grace key, that has a timeout() value. This is the time in milliseconds that the acceptor pool will wait for children to exit before starting to shut them down when terminating. This allows connections to be gracefully closed.

To start accepting connections using the acceptor_pool call accept_socket/3.

See also: acceptor, supervisor.

Summary

Types

acceptor_spec/0

name/0

pool/0

pool_flags/0

Callbacks

init/1

Functions

accept_socket(Pool, Sock, Acceptors)

Ask acceptor_poolPool to accept on the listen socket Sock with Acceptors number of acceptors.

count_children(Pool)

Count the children of the acceptor_pool.

start_link(Module, Args)

Start an acceptor_pool with callback module Module and argument Args.

start_link(Name, Module, Args)

Start an acceptor_pool with name Name, callback module Module and argument Args.

which_children(Pool)

List the children of the acceptor_pool.

which_sockets(Pool)

List the listen sockets being used by the acceptor_pool.

Types

acceptor_spec/0

-type acceptor_spec() ::
          #{id := term(),
            start := {module(), any(), [acceptor:option()]},
            restart => transient | temporary,
            shutdown => timeout() | brutal_kill,
            grace => timeout(),
            type => worker | supervisor,
            modules => [module()] | dynamic}.

name/0

-type name() :: {inet:ip_address(), inet:port_number()} | inet:returned_non_ip_address().

pool/0

-type pool() :: pid() | atom() | {atom(), node()} | {via, module(), any()} | {global, any()}.

pool_flags/0

-type pool_flags() :: #{intensity => non_neg_integer(), period => pos_integer()}.

Callbacks

init/1

-callback init(Args) -> {ok, {PoolFlags, [AcceptorSpec, ...]}} | ignore
                  when Args :: any(), PoolFlags :: pool_flags(), AcceptorSpec :: acceptor_spec().

Functions

accept_socket(Pool, Sock, Acceptors)

-spec accept_socket(Pool, Sock, Acceptors) -> {ok, Ref} | {error, Reason}
                       when
                           Pool :: pool(),
                           Sock :: gen_tcp:socket(),
                           Acceptors :: pos_integer(),
                           Ref :: reference(),
                           Reason :: inet:posix().

Ask acceptor_poolPool to accept on the listen socket Sock with Acceptors number of acceptors.

Returns {ok, Ref} on success or {error, Reason} on failure. If acceptors fail to accept connections an exit signal is sent Sock.

count_children(Pool)

-spec count_children(Pool) -> Counts
                        when
                            Pool :: pool(),
                            Counts :: [{spec | active | workers | supervisors, non_neg_integer()}].

Count the children of the acceptor_pool.

Processes that are waiting for a socket are not included in active.

See also: supervisor:count_children/1.

start_link(Module, Args)

-spec start_link(Module, Args) -> {ok, Pid} | ignore | {error, Reason}
                    when Module :: module(), Args :: any(), Pid :: pid(), Reason :: any().

Start an acceptor_pool with callback module Module and argument Args.

See also: start_link/3.

start_link(Name, Module, Args)

-spec start_link(Name, Module, Args) -> {ok, Pid} | ignore | {error, Reason}
                    when
                        Name :: {local, atom()} | {via, module, any()} | {global, any()},
                        Module :: module(),
                        Args :: any(),
                        Pid :: pid(),
                        Reason :: any().

Start an acceptor_pool with name Name, callback module Module and argument Args.

This function is equivalent to supervisor:start_link/3 except starts an acceptor_pool instead of a supervisor.

See also: supervisor:start_link/3.

which_children(Pool)

-spec which_children(Pool) -> [{Id, Child, Type, Modules}]
                        when
                            Pool :: pool(),
                            Id :: {term(), PeerName :: name(), SockName :: name(), Ref :: reference()},
                            Child :: pid(),
                            Type :: worker | supervisor,
                            Modules :: [module()] | dynamic.

List the children of the acceptor_pool.

This function is equivalent to supervisor:which_children/1 except that the peer name, listen socket name and a unique reference are combined with the id from init/1.

Processes that are waiting for a socket are not included.

See also: supervisor:which_children/1.

which_sockets(Pool)

-spec which_sockets(Pool) -> [{SockModule, SockName, Sock, Ref}]
                       when
                           Pool :: pool(),
                           SockModule :: module(),
                           SockName :: name(),
                           Sock :: gen_tcp:socket(),
                           Ref :: reference().

List the listen sockets being used by the acceptor_pool.