=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
>:
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