NAME
UniEvent::Udp - encapsulate UDP communication for both clients and servers
SYNOPSIS
# client
my $client = UniEvent::Udp->new;
$client->recv_start;
$client->receive_callback(sub {
my ($client, $data, $peer_addr, $flags, $error) = @_;
die("receive data error: $error\n") if $error;
...
});
my $dest = Net::SockAddr::Inet4->new($ip, $port);
$client->send($data, $dest, sub {
my ($client, $error) = @_;
die("sending data error: $error\n") if $error;
...
});
$client->loop->run;
# server
my $server = UniEvent::Udp->new;
$server->bind($host, $port);
$server->recv_start;
$server->receive_callback(sub {
my ($server, $data, $peer_addr, $flags, $error) = @_;
...
say "client ", $peer_addr, " has sent us ", length($data), " bytes";
});
$server->loop->run;DESCRIPTION
Udp handle allows to send and receive UDP-datagrams, including broadcasting and multicasting capabilities. It is able to work over IPv4 as well as over IPv6 protocols (aka dual stack mode), the difference between them is abstracted from user.
The handle is inherited from UniEvent::Handle.
METHODS
All methods of UniEvent::Handle also apply.
new([$loop = default], [$domain = AF_UNSPEC], [$flags = 0])
Constructs new Udp handle and binds it to the specified event loop.
If $domain or $flags are specified then underlying socket is created immediately and is available via fileno(). Otherwise socket creation is postponed.
The only flag at the moment is UniEvent::Udp::RECVMMSG. See "CONSTANTS" in UniEvent::Udp.
open($fd)
Open an existing file descriptor as Udp handle; it is expected that $sock is valid stream socket.
bind($host, $port, [$hints], [$flags])
Bind the handle to an address, determined by $host, and the specified $port.
The $host can be a domain name, human-readable IP address or special string *, which means "bind to every available network interface on the host".
$port can be 0 in which case handle will be bound to a some available port. It can later be inspected via
say $udp->sockaddr->port;If $host is a domain name, it is synchronously resolved to address using the specified $hints, see UniEvent::Resolver for the details.
$flags is the bitmask of flags for binding. UE::Udp::IPV6ONLY and UE::Udp::REUSEADDR are supported. See "CONSTANTS" in UniEvent::Udp.
bind_addr($addr, $flags)
Bind the handle to an address. $addr can be either a Net::SockAddr object or perl-style packed address (what sockaddr_in returns). For details on $flags see bind().
connect($sockaddr)
Associate the UDP handle to a remote address and port, so every message sent by this handle is automatically sent to that destination.
Calling this method with an empty addr disconnects the handle.
$sockaddr can be either a Net::SockAddr object or perl-style packed address (what sockaddr_in returns).
connect($host, $port, [$hints])
$host is synchronously resolved to address using the specified $hints and then the above version of connect() is called.
recv_start([$callback])
Instructs to watch for and receive (read) data from the socket. It reads until error condition is met, or until recv_stop.
Receive callback/event will be invoked when new data is received.
If $callback is specified it is added as ->receive_event()->add($callback)
recv_stop()
Stop receiving data from the socket.
receive_callback($sub)
receive_event()
Callbacks set via these methods will be invoked when new data from peer has been received.
Callback signature:
my ($udp, $data, $peer_addr, $flags, $error) = @_;Where $udp is the udp handle object.
$data is the data has been received.
$peer_addr is the peer address that sent $data as Net::SockAddr object.
$flags is a bitmask of one of "FLAGS" in UniEvent::Udp.
$error is an optional XS::ErrorCode object and if it is present then $data may be undefined.
See "EVENT CALLBACKS" in UniEvent
send($data, $destination, [$callback])
Sends data over the UDP socket to the $destination (which have to be specified in the form of Net::SockAddr or perl-style packed address, what sockaddr_in returns). One-shot $callback will be invoked upon successful operation completion.
You should not specify $destination if handle has been previously connected via connect().
Returns UniEvent::Request::Send object which is an internal purpose object and returned for request tracking purposes only.
send_callback($sub)
send_event()
Callbacks set via these methods will be invoked every time send operation caused by send() method is completed.
Callback signature:
my ($udp, $error, $send_request) = @_;Where $udp is the udp handle object.
$error is an optional XS::ErrorCode object.
$send_request is an UniEvent::Request::Send object, which is an internal purpose object and passed to callback for request tracking purposes only.
See "EVENT CALLBACKS" in UniEvent
event_listener($delegate, [$weak])
Methods on_receive, on_send will be called.
See "EVENT LISTENER" in UniEvent
sockaddr()
Returns address (as Net::SockAddr object) of the local endpoint.
If socket is not connected/bound, undef is returned.
peeraddr()
Returns address (as Net::SockAddr object) of the remote (peer) endpoint.
if socket is not connected, undef is returned.
set_membership($multicast_addr, $interface_addr, $membership)
Set $membership for a multicast address. The $membership can be either UE::Udp::JOIN_GROUP or UE::Udp::LEAVE_GROUP.
set_source_membership($multicast_addr, $interface_addr, $source_addr, $membership)
Set $membership for a source-specific multicast group. The $membership can be either UE::Udp::JOIN_GROUP or UE::Udp::LEAVE_GROUP.
set_multicast_loop($enabled)
Set IP multicast loop flag. Makes multicast packets loop back to local sockets.
set_multicast_ttl($value)
Set the multicast ttl.
set_multicast_interface()
Set the multicast interface to send or receive data on.
set_broadcast($enabled)
Set broadcast on or off.
set_ttl($value)
Set the time to live.
recv_buffer_size([$value])
Gets or sets the size of the receive buffer that the operating system uses for the socket.
send_buffer_size([$value])
Gets or sets the size of the send buffer that the operating system uses for the socket.
send_queue_size()
Returns the amount of queued bytes waiting to be sent.
CONSTANTS
FLAGS
PARTIAL
Indicates message was truncated because read buffer was too small. The remainder was discarded by the OS.
IPV6ONLY
Disables dual stack mode.
REUSEADDR
Indicates that the message was received by recvmmsg.
RECVMMSG
Indicates that recvmmsg should be used, if available