wren/manual_src/pages/api/udp.html

{# retoor <retoor@molodetz.nl> #}
{% extends 'page.html' %}

{% set page_title = "udp" %}
{% set breadcrumb = [{"url": "api/index.html", "title": "API Reference"}, {"title": "udp"}] %}
{% set prev_page = {"url": "api/tls.html", "title": "tls"} %}
{% set next_page = {"url": "api/uuid.html", "title": "uuid"} %}

{% block article %}
                <h1>udp</h1>

                <p>The <code>udp</code> module provides UDP (User Datagram Protocol) socket functionality for connectionless networking. UDP is useful for applications requiring fast, lightweight communication without the overhead of TCP connection management.</p>

                <pre><code>import "udp" for UdpSocket, UdpMessage</code></pre>

                <div class="toc">
                    <h4>On This Page</h4>
                    <ul>
                        <li><a href="#udpsocket-class">UdpSocket Class</a></li>
                        <li><a href="#udpmessage-class">UdpMessage Class</a></li>
                        <li><a href="#examples">Examples</a></li>
                    </ul>
                </div>

                <h2 id="udpsocket-class">UdpSocket Class</h2>

                <div class="class-header">
                    <h3>UdpSocket</h3>
                    <p>UDP datagram socket for sending and receiving messages</p>
                </div>

                <h3>Constructor</h3>

                <div class="method-signature">
                    <span class="method-name">UdpSocket.new</span>() &#8594; <span class="type">UdpSocket</span>
                </div>
                <p>Creates a new UDP socket.</p>
                <pre><code>var socket = UdpSocket.new()</code></pre>

                <h3>Methods</h3>

                <div class="method-signature">
                    <span class="method-name">bind</span>(<span class="param">host</span>, <span class="param">port</span>)
                </div>
                <p>Binds the socket to a local address and port. Required before receiving messages.</p>
                <ul class="param-list">
                    <li><span class="param-name">host</span> <span class="param-type">(String)</span> - Local address to bind (e.g., "0.0.0.0" for all interfaces)</li>
                    <li><span class="param-name">port</span> <span class="param-type">(Num)</span> - Port number to bind</li>
                </ul>
                <pre><code>socket.bind("0.0.0.0", 8080)</code></pre>

                <div class="method-signature">
                    <span class="method-name">send</span>(<span class="param">data</span>, <span class="param">host</span>, <span class="param">port</span>)
                </div>
                <p>Sends a datagram to the specified address. Async operation.</p>
                <ul class="param-list">
                    <li><span class="param-name">data</span> <span class="param-type">(String)</span> - Data to send</li>
                    <li><span class="param-name">host</span> <span class="param-type">(String)</span> - Destination hostname or IP</li>
                    <li><span class="param-name">port</span> <span class="param-type">(Num)</span> - Destination port</li>
                </ul>
                <pre><code>socket.send("Hello!", "192.168.1.100", 8080)</code></pre>

                <div class="method-signature">
                    <span class="method-name">receive</span>() &#8594; <span class="type">UdpMessage</span>
                </div>
                <p>Receives a datagram. Blocks until data arrives. Returns a UdpMessage containing the data and sender information.</p>
                <pre><code>var msg = socket.receive()
System.print("From %(msg.address):%(msg.port): %(msg.data)")</code></pre>

                <div class="method-signature">
                    <span class="method-name">close</span>()
                </div>
                <p>Closes the socket.</p>
                <pre><code>socket.close()</code></pre>

                <div class="method-signature">
                    <span class="method-name">setBroadcast</span>(<span class="param">enabled</span>)
                </div>
                <p>Enables or disables broadcast mode. When enabled, the socket can send to broadcast addresses.</p>
                <ul class="param-list">
                    <li><span class="param-name">enabled</span> <span class="param-type">(Bool)</span> - True to enable broadcast</li>
                </ul>
                <pre><code>socket.setBroadcast(true)
socket.send("Broadcast message", "255.255.255.255", 8080)</code></pre>

                <div class="method-signature">
                    <span class="method-name">setMulticastTTL</span>(<span class="param">ttl</span>)
                </div>
                <p>Sets the time-to-live for multicast packets.</p>
                <ul class="param-list">
                    <li><span class="param-name">ttl</span> <span class="param-type">(Num)</span> - TTL value (1-255)</li>
                </ul>
                <pre><code>socket.setMulticastTTL(64)</code></pre>

                <div class="method-signature">
                    <span class="method-name">setMulticastLoopback</span>(<span class="param">enabled</span>)
                </div>
                <p>Enables or disables multicast loopback. When enabled, the socket receives its own multicast messages.</p>
                <ul class="param-list">
                    <li><span class="param-name">enabled</span> <span class="param-type">(Bool)</span> - True to enable loopback</li>
                </ul>
                <pre><code>socket.setMulticastLoopback(false)</code></pre>

                <div class="method-signature">
                    <span class="method-name">joinMulticast</span>(<span class="param">group</span>)
                </div>
                <p>Joins a multicast group on the default interface.</p>
                <ul class="param-list">
                    <li><span class="param-name">group</span> <span class="param-type">(String)</span> - Multicast group address (e.g., "239.255.0.1")</li>
                </ul>
                <pre><code>socket.joinMulticast("239.255.0.1")</code></pre>

                <div class="method-signature">
                    <span class="method-name">joinMulticast</span>(<span class="param">group</span>, <span class="param">iface</span>)
                </div>
                <p>Joins a multicast group on a specific interface.</p>
                <ul class="param-list">
                    <li><span class="param-name">group</span> <span class="param-type">(String)</span> - Multicast group address</li>
                    <li><span class="param-name">iface</span> <span class="param-type">(String)</span> - Local interface address to join from</li>
                </ul>
                <pre><code>socket.joinMulticast("239.255.0.1", "192.168.1.100")</code></pre>

                <div class="method-signature">
                    <span class="method-name">leaveMulticast</span>(<span class="param">group</span>)
                </div>
                <p>Leaves a multicast group on the default interface.</p>
                <ul class="param-list">
                    <li><span class="param-name">group</span> <span class="param-type">(String)</span> - Multicast group address</li>
                </ul>
                <pre><code>socket.leaveMulticast("239.255.0.1")</code></pre>

                <div class="method-signature">
                    <span class="method-name">leaveMulticast</span>(<span class="param">group</span>, <span class="param">iface</span>)
                </div>
                <p>Leaves a multicast group on a specific interface.</p>
                <ul class="param-list">
                    <li><span class="param-name">group</span> <span class="param-type">(String)</span> - Multicast group address</li>
                    <li><span class="param-name">iface</span> <span class="param-type">(String)</span> - Local interface address</li>
                </ul>
                <pre><code>socket.leaveMulticast("239.255.0.1", "192.168.1.100")</code></pre>

                <h3>Properties</h3>

                <div class="method-signature">
                    <span class="method-name">localAddress</span> &#8594; <span class="type">String</span>
                </div>
                <p>Returns the local address the socket is bound to.</p>
                <pre><code>System.print("Bound to: %(socket.localAddress)")</code></pre>

                <div class="method-signature">
                    <span class="method-name">localPort</span> &#8594; <span class="type">Num</span>
                </div>
                <p>Returns the local port the socket is bound to.</p>
                <pre><code>System.print("Port: %(socket.localPort)")</code></pre>

                <h2 id="udpmessage-class">UdpMessage Class</h2>

                <div class="class-header">
                    <h3>UdpMessage</h3>
                    <p>Represents a received UDP datagram</p>
                </div>

                <h3>Properties</h3>

                <div class="method-signature">
                    <span class="method-name">data</span> &#8594; <span class="type">String</span>
                </div>
                <p>The data contained in the message.</p>

                <div class="method-signature">
                    <span class="method-name">address</span> &#8594; <span class="type">String</span>
                </div>
                <p>The IP address of the sender.</p>

                <div class="method-signature">
                    <span class="method-name">port</span> &#8594; <span class="type">Num</span>
                </div>
                <p>The port number of the sender.</p>

                <pre><code>var msg = socket.receive()
System.print("Data: %(msg.data)")
System.print("From: %(msg.address):%(msg.port)")</code></pre>

                <h2 id="examples">Examples</h2>

                <h3>Simple UDP Server</h3>
                <pre><code>import "udp" for UdpSocket

var socket = UdpSocket.new()
socket.bind("0.0.0.0", 8080)

System.print("UDP server listening on port 8080")

while (true) {
    var msg = socket.receive()
    System.print("Received from %(msg.address):%(msg.port): %(msg.data)")

    socket.send("Echo: %(msg.data)", msg.address, msg.port)
}</code></pre>

                <h3>Simple UDP Client</h3>
                <pre><code>import "udp" for UdpSocket

var socket = UdpSocket.new()
socket.bind("0.0.0.0", 0)

socket.send("Hello, server!", "127.0.0.1", 8080)

var response = socket.receive()
System.print("Server responded: %(response.data)")

socket.close()</code></pre>

                <h3>Broadcast Discovery</h3>
                <pre><code>import "udp" for UdpSocket
import "timer" for Timer

var socket = UdpSocket.new()
socket.bind("0.0.0.0", 0)
socket.setBroadcast(true)

System.print("Sending discovery broadcast...")
socket.send("DISCOVER", "255.255.255.255", 9999)

System.print("Waiting for responses...")

var timeout = false
var timeoutFiber = Fiber.new {
    Timer.sleep(3000)
    timeout = true
}
timeoutFiber.call()

while (!timeout) {
    var msg = socket.receive()
    System.print("Found device at %(msg.address): %(msg.data)")
}

socket.close()</code></pre>

                <h3>Multicast Group</h3>
                <pre><code>import "udp" for UdpSocket

var MULTICAST_GROUP = "239.255.0.1"
var MULTICAST_PORT = 5000

var socket = UdpSocket.new()
socket.bind("0.0.0.0", MULTICAST_PORT)
socket.joinMulticast(MULTICAST_GROUP)
socket.setMulticastLoopback(true)

System.print("Joined multicast group %(MULTICAST_GROUP)")

socket.send("Hello multicast!", MULTICAST_GROUP, MULTICAST_PORT)

var msg = socket.receive()
System.print("Received: %(msg.data) from %(msg.address)")

socket.leaveMulticast(MULTICAST_GROUP)
socket.close()</code></pre>

                <h3>DNS-Style Query/Response</h3>
                <pre><code>import "udp" for UdpSocket
import "json" for Json

var socket = UdpSocket.new()
socket.bind("0.0.0.0", 0)

var query = Json.stringify({
    "type": "lookup",
    "name": "example.local"
})

socket.send(query, "192.168.1.1", 5353)

var response = socket.receive()
var result = Json.parse(response.data)
System.print("Lookup result: %(result)")

socket.close()</code></pre>

                <h3>UDP Ping</h3>
                <pre><code>import "udp" for UdpSocket
import "sysinfo" for SysInfo

var socket = UdpSocket.new()
socket.bind("0.0.0.0", 0)

var target = "127.0.0.1"
var port = 8080

for (i in 1..5) {
    var start = SysInfo.hrtime
    socket.send("PING %(i)", target, port)

    var msg = socket.receive()
    var elapsed = (SysInfo.hrtime - start) / 1000000

    System.print("Reply from %(msg.address): %(elapsed) ms")
}

socket.close()</code></pre>

                <div class="admonition note">
                    <div class="admonition-title">Note</div>
                    <p>UDP is connectionless and does not guarantee delivery. Messages may be lost, duplicated, or arrive out of order. Use TCP (<code>net</code> module) when reliability is required.</p>
                </div>

                <div class="admonition tip">
                    <div class="admonition-title">Tip</div>
                    <p>When binding to port 0, the system automatically assigns an available port. Use <code>localPort</code> to retrieve the assigned port number.</p>
                </div>

                <div class="admonition warning">
                    <div class="admonition-title">Warning</div>
                    <p>Multicast group addresses must be in the range 224.0.0.0 to 239.255.255.255. Using addresses outside this range will cause errors.</p>
                </div>
{% endblock %}