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.

May return error

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.

May return error

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().

May return error

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).

May return error

connect($host, $port, [$hints])

$host is synchronously resolved to address using the specified $hints and then the above version of connect() is called.

May return error

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)

May return error

recv_stop()

Stop receiving data from the socket.

May return error

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.

May return error

peeraddr()

Returns address (as Net::SockAddr object) of the remote (peer) endpoint.

if socket is not connected, undef is returned.

May return error

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.

May return error

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.

May return error

set_multicast_loop($enabled)

Set IP multicast loop flag. Makes multicast packets loop back to local sockets.

May return error

set_multicast_ttl($value)

Set the multicast ttl.

May return error

set_multicast_interface()

Set the multicast interface to send or receive data on.

May return error

set_broadcast($enabled)

Set broadcast on or off.

May return error

set_ttl($value)

Set the time to live.

May return error

recv_buffer_size([$value])

Gets or sets the size of the receive buffer that the operating system uses for the socket.

May return error

send_buffer_size([$value])

Gets or sets the size of the send buffer that the operating system uses for the socket.

May return error

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

GROUP MEMBERSHIP

LEAVE_GROUP

JOIN_GROUP

cpanm UniEvent

perl -MCPAN -e shell
install UniEvent