|
|
Net::UDP - UDP sockets interface module
use Net::Gen; # optional
use Net::Inet; # optional
use Net::UDP;
The Net::UDP module provides services for UDP communications
over sockets. It is layered atop the
Net::Inet
and
Net::Gen
modules, which are part of the same distribution.
The following methods are provided by the Net::UDP module
itself, rather than just being inherited from
Net::Inet
or
Net::Gen.
Usage:
$obj = new Net::UDP;
$obj = new Net::UDP $desthost, $destservice;
$obj = new Net::UDP \%parameters;
$obj = new Net::UDP $desthost, $destservice, \%parameters;
$obj = 'Net::UDP'->new();
$obj = 'Net::UDP'->new($desthost);
$obj = 'Net::UDP'->new($desthost, $destservice);
$obj = 'Net::UDP'->new(\%parameters);
$obj = 'Net::UDP'->new($desthost, $destservice, \%parameters);
Returns a newly-initialised object of the given class. If called
for a derived class, no validation of the supplied parameters
will be performed. (This is so that the derived class can add
the parameter validation it needs to the object before allowing
the validation.) Otherwise, it will cause the parameters to be
validated by calling its init method, which Net::UDP
inherits from
Net::Inet. In particular, this means that if
both a host and a service are given, that an object will only be
returned if a connect() call was successful.
The examples above show the indirect object syntax which many prefer, as well as the guaranteed-to-be-safe static method call. There are occasional problems with the indirect object syntax, which tend to be rather obscure when encountered. See http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/1998-01/msg01674.html for details.
Usage:
$ok = $obj->PRINT(@args);
$ok = print $tied_fh @args;
This method, intended to be used with tied filehandles, behaves like one
of two inherited methods from the
Net::Gen class, depending on the
setting of the object parameter unbuffered_output. If that parameter
is false (the default), then the normal print() builtin is used.
If the unbuffered_output parameter is true, then each print()
operation will actually result in a call to the send method,
requiring that the object be connected or that its message is in
response to its last normal recv() (with a flags parameter of
0). The value of the $\ variable is ignored in that case, but
the $, variable is still used if the @args array has multiple
elements.
Usage:
$line_or_datagram = $obj->READLINE;
$line_or_datagram = <TIED_FH>;
$line_or_datagram = readline(TIED_FH);
@lines_or_datagrams = $obj->READLINE;
@lines_or_datagrams = <TIED_FH>;
@lines_or_datagrams = readline(TIED_FH);
This method, intended to be used with tied filehandles, behaves
like one of two inherited methods from the Net::Gen class,
depending on the setting of the object parameter
unbuffered_input. If that parameter is false (the default),
then this method does line-buffering of its input as defined by
the current setting of the $/ variable. If the
<unbuffered_input> parameter is true, then the input records will
be exact recv() datagrams, disregarding the setting of the $/
variable. Note that invoking the READLINE method in list
context is likely to hang, since UDP sockets typically don't
return EOF.
none.
There are no object parameters registered by the Net::UDP module itself.
The following object parameters are registered by the Net::UDP module
(as distinct from being inherited from
Net::Gen
or
Net::Inet):
If true, the READLINE operation on tied filehandles will return each recv()
buffer as though it were a single separate line, independently of the setting
of the $/ variable. The default is false, which causes the READLINE
interface to return lines split at boundaries as appropriate for $/.
(The READLINE method for tied filehandles is the <FH>
operation.) Note that calling the READLINE method
in list context is likely to hang for UDP sockets.
If true, the PRINT operation on tied filehandles will result in calls to
the send() builtin rather than the print() builtin, as described in PRINT
above. The default is false, which causes the PRINT method to use the
print() builtin.
This object parameter's value is unreliable on getparam or getparams
method calls. It is provided as a handy way to set both the
unbuffered_output and unbuffered_input object parameters to the same
value at the same time during new calls.
Tieing of scalars to a UDP handle is supported by inheritance
from the TIESCALAR method of
Net::Gen. That method only
succeeds if a call to a new method results in an object for
which the isconnected method returns true, which is why it is
mentioned in regard to this module.
Example:
tie $x,'Net::UDP',0,'daytime' or die "tie to Net::UDP: $!";
$x = "\n"; $x = "\n";
print $y if defined($y = $x);
untie $x;
This is an expensive re-implementation of date on many
machines.
Each assignment to the tied scalar is really a call to the put
method (via the STORE method), and each read from the tied
scalar is really a call to the READLINE method (via the
FETCH method).
As inherited from
Net::Inet
and
Net::Gen,
with the addition of
unbuffered I/O options for the READLINE and PRINT methods.
Example:
tie *FH,'Net::UDP',{unbuffered_IO => 1, thisport => $n, thishost => 0}
or die;
while (<FH>) {
last if is_shutdown_msg($_);
print FH response($_);
}
untie *FH;
This shows how to make a UDP-based filehandle return (and send) datagrams
even when used in the usual perlish paradigm. For some applications,
this can be helpful to avoid cluttering the message processing code with
the details of handling datagrams. In particular, this example relies on
the underlying support for replying to the last address in a recvfrom()
for datagram sockets, thus hiding the details of tracking and using
that information.
none
This module has been tested with threaded perls, and should be as thread-safe as perl itself. (As of 5.005_03 and 5.005_57, that's not all that safe just yet.) It also works with interpreter-based threads ('ithreads') in more recent perl releases.
Spider Boardman <spidb@cpan.org>