=head1 NAME

Net::SIP:::SocketPool - manage sockets related to a leg

=head1 SYNOPSIS

  my $pool = Net::SIP::SocketPool->new(...)
  $pool->sendto($packet, [ip,port,family], \&callback)

=head1 DESCRIPTION

B<SocketPool> manages a collection of sockets associated with a B<Leg>. This is
usually an unconnected socket (i.e. UDP or TCP listen socket) and mayby some
connected sockets.
While in UDP a packet can be received and sent using an unconnected socket this
is not possible in TCP and therefore these connected socket have to be
maintained somehow. Also, it is expected in TCP that a response will be sent
back through the same TCP connection as the request came in, if possible.

B<SocketPool> is usually not used directly but will be created when a new B<Leg>
gets created.

=head1 CONSTRUCTOR

=over 4

=item new (PROTO, FD, DST, CONNECTED)

The constructer creates a new B<SocketPool> for protocol B<PROTO> (C<udp> or
C<tcp>) with B<FD> as the master socket.
If B<CONNECTED> is true this master socket is connected and B<DST> will in this
case be interpreted as the peer of the socket. But a connected master socket
makes only sense for UDP and only if the communication should be limited to
specific party, like an outgoing SIP proxy.
In the common case that B<CONNECTED> is false the optional B<DST>
given as C<< [ip, port, family] >> will be interpreted as restriction for the
communication, i.e. it will be forced as destination in B<sendto> no matter what
was given and it will be checked that any received data origin from the expected
peer B<DST>.

=back

=head1 METHODS

=over 4

=item sendto(PKT, DST, CALLBACK)

This method is used indirectly from B<Leg::deliver> to deliver a new packet to
its destinination.

This will deliver the L<Net::SIP::Packet> B<PKT> to the target B<DST> given as
C<< [ip, port, family] >> and will invoke B<CALLBACK> when done. Callback can be
anything accepted by B<invoke_callback> from L<Net::SIP::Util>.

With TCP the B<SocketPool> will try to find an existing connected socket to the
target first before creating a new one. For response packets it will prefer the
socket where the request packet came in, if possible.

With UDP instead it will just use the master socket for sending.

=item master

This will just return the FD for the master socket. This is used by B<Leg> in
case the B<SocketPool> was created outside the B<Leg>.

=item attach_eventloop(LOOP, CALLBACK)

This attaches the B<SocketPool> to a L<Net::SIP::Dispatcher::EventLoop> object
so that it can be used for event based I/O. This attaches B<CALLBACK> as read
handler to the given B<LOOP> to handle new packets coming in through the sockets
inside the B<SocketPool>. It will accept any callback suitable for
B<invoke_callback> and will invoke it with C<< [PKT, FROM] >> where B<PKT> is
the freshly read L<Net::SIP::Packet> and B<FROM> the origin of this packet as
C<< [ip, port, family] >>.

If B<LOOP> is undef it will just detach from the current loop.

This function is used from inside L<Net::SIP::Dispatcher> to attach a legs
sockets to the event loop and process incoming data.

=back

Additionally to these methods the internal configuration can be adjusted with
C<use> or C<import>:

    use Net::SIP::SocketPool (MAX_SIP_HEADER => 2**14, ... );

The following settings are possible this way:

=over 4

=item MAX_SIP_HEADER

maximum size of SIP header, default C<2**14>

=item MAX_SIP_BODY

maximum size of SIP body, default C<2**16>

=item MAX_TIDLIST

This is maximum size of remembered incoming requests per socket. These requests
need to be remembered so that outgoing responses can be sent back through the
same connection as the request came in.
This defaults to 30.

=item MIN_EXPIRE, MAX_EXPIRE

The minimal time for socket expiration and the maximum time. These default to 15
and 120 (seconds). The exact time for expiration depends on the number of
sockets in the socketgroup, i.e. the more sockets the shorter the expiration
timeout.

=item CONNECT_TIMEOUT

The timeout used for establishing a TCP connection. Default to 10 (seconds).

=item TCP_READSIZE

The amount of data it tries to read within a single sysread, default 2**16.

=back