UniEvent::Udp - encapsulate UDP communication for both clients and servers
# 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;
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.
All methods of UniEvent::Handle also apply.
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.
$domain
$flags
fileno()
The only flag at the moment is UniEvent::Udp::RECVMMSG. See "CONSTANTS" in UniEvent::Udp.
UniEvent::Udp::RECVMMSG
Open an existing file descriptor as Udp handle; it is expected that $sock is valid stream socket.
$sock
May return error
Bind the handle to an address, determined by $host, and the specified $port.
$host
$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
0
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.
$hints
$flags is the bitmask of flags for binding. UE::Udp::IPV6ONLY and UE::Udp::REUSEADDR are supported. See "CONSTANTS" in UniEvent::Udp.
UE::Udp::IPV6ONLY
UE::Udp::REUSEADDR
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().
$addr
sockaddr_in
bind()
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).
$sockaddr
$host is synchronously resolved to address using the specified $hints and then the above version of connect() is called.
connect()
Instructs to watch for and receive (read) data from the socket. It reads until error condition is met, or until recv_stop.
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)
$callback
Stop receiving data from the socket.
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.
$udp
$data is the data has been received.
$data
$peer_addr is the peer address that sent $data as Net::SockAddr object.
$peer_addr
$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.
$error
See "EVENT CALLBACKS" in UniEvent
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.
$destination
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.
Callbacks set via these methods will be invoked every time send operation caused by send() method is completed.
send()
my ($udp, $error, $send_request) = @_;
$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.
$send_request
Methods on_receive, on_send will be called.
on_receive
on_send
See "EVENT LISTENER" in UniEvent
Returns address (as Net::SockAddr object) of the local endpoint.
If socket is not connected/bound, undef is returned.
Returns address (as Net::SockAddr object) of the remote (peer) endpoint.
if socket is not connected, undef is returned.
Set $membership for a multicast address. The $membership can be either UE::Udp::JOIN_GROUP or UE::Udp::LEAVE_GROUP.
$membership
UE::Udp::JOIN_GROUP
UE::Udp::LEAVE_GROUP
Set $membership for a source-specific multicast group. The $membership can be either UE::Udp::JOIN_GROUP or UE::Udp::LEAVE_GROUP.
Set IP multicast loop flag. Makes multicast packets loop back to local sockets.
Set the multicast ttl.
Set the multicast interface to send or receive data on.
Set broadcast on or off.
Set the time to live.
Gets or sets the size of the receive buffer that the operating system uses for the socket.
Gets or sets the size of the send buffer that the operating system uses for the socket.
Returns the amount of queued bytes waiting to be sent.
Indicates message was truncated because read buffer was too small. The remainder was discarded by the OS.
Disables dual stack mode.
Indicates that the message was received by recvmmsg.
Indicates that recvmmsg should be used, if available
To install UniEvent, copy and paste the appropriate command in to your terminal.
cpanm
cpanm UniEvent
CPAN shell
perl -MCPAN -e shell install UniEvent
For more information on module installation, please visit the detailed CPAN module installation guide.