2026-01-25 13:09:28 +01:00
<!DOCTYPE html>
<!-- retoor <retoor@molodetz.nl> -->
< html lang = "en" >
< head >
< meta charset = "UTF-8" >
< meta name = "viewport" content = "width=device-width, initial-scale=1.0" >
< title > udp - Wren-CLI Manual</ title >
< link rel = "stylesheet" href = "../css/style.css" >
</ head >
< body >
< button class = "mobile-menu-toggle" > Menu</ button >
< div class = "container" >
< aside class = "sidebar" >
< div class = "sidebar-header" >
< h1 >< a href = "../index.html" > Wren-CLI</ a ></ h1 >
< div class = "version" > v0.4.0</ div >
</ div >
< nav class = "sidebar-nav" >
< div class = "section" >
< span class = "section-title" > Getting Started</ span >
< ul >
< li >< a href = "../getting-started/index.html" > Overview</ a ></ li >
< li >< a href = "../getting-started/installation.html" > Installation</ a ></ li >
< li >< a href = "../getting-started/first-script.html" > First Script</ a ></ li >
< li >< a href = "../getting-started/repl.html" > Using the REPL</ a ></ li >
</ ul >
</ div >
< div class = "section" >
< span class = "section-title" > Language</ span >
< ul >
< li >< a href = "../language/index.html" > Syntax Overview</ a ></ li >
< li >< a href = "../language/classes.html" > Classes</ a ></ li >
< li >< a href = "../language/methods.html" > Methods</ a ></ li >
< li >< a href = "../language/control-flow.html" > Control Flow</ a ></ li >
< li >< a href = "../language/fibers.html" > Fibers</ a ></ li >
< li >< a href = "../language/modules.html" > Modules</ a ></ li >
</ ul >
</ div >
< div class = "section" >
< span class = "section-title" > API Reference</ span >
< ul >
< li >< a href = "index.html" > Overview</ a ></ li >
< li >< a href = "string.html" > String</ a ></ li >
< li >< a href = "number.html" > Num</ a ></ li >
< li >< a href = "argparse.html" > argparse</ a ></ li >
< li >< a href = "base64.html" > base64</ a ></ li >
< li >< a href = "crypto.html" > crypto</ a ></ li >
< li >< a href = "dataset.html" > dataset</ a ></ li >
< li >< a href = "datetime.html" > datetime</ a ></ li >
< li >< a href = "dns.html" > dns</ a ></ li >
< li >< a href = "env.html" > env</ a ></ li >
< li >< a href = "fswatch.html" > fswatch</ a ></ li >
< li >< a href = "html.html" > html</ a ></ li >
< li >< a href = "http.html" > http</ a ></ li >
< li >< a href = "io.html" > io</ a ></ li >
< li >< a href = "jinja.html" > jinja</ a ></ li >
< li >< a href = "json.html" > json</ a ></ li >
< li >< a href = "markdown.html" > markdown</ a ></ li >
< li >< a href = "math.html" > math</ a ></ li >
< li >< a href = "net.html" > net</ a ></ li >
< li >< a href = "os.html" > os</ a ></ li >
< li >< a href = "pathlib.html" > pathlib</ a ></ li >
< li >< a href = "regex.html" > regex</ a ></ li >
< li >< a href = "scheduler.html" > scheduler</ a ></ li >
< li >< a href = "signal.html" > signal</ a ></ li >
< li >< a href = "sqlite.html" > sqlite</ a ></ li >
< li >< a href = "subprocess.html" > subprocess</ a ></ li >
< li >< a href = "sysinfo.html" > sysinfo</ a ></ li >
< li >< a href = "tempfile.html" > tempfile</ a ></ li >
< li >< a href = "timer.html" > timer</ a ></ li >
< li >< a href = "tls.html" > tls</ a ></ li >
< li >< a href = "udp.html" class = "active" > udp</ a ></ li >
< li >< a href = "uuid.html" > uuid</ a ></ li >
< li >< a href = "wdantic.html" > wdantic</ a ></ li >
< li >< a href = "web.html" > web</ a ></ li >
< li >< a href = "websocket.html" > websocket</ a ></ li >
</ ul >
</ div >
< div class = "section" >
< span class = "section-title" > Tutorials</ span >
< ul >
< li >< a href = "../tutorials/index.html" > Tutorial List</ a ></ li >
< li >< a href = "../tutorials/http-client.html" > HTTP Client</ a ></ li >
< li >< a href = "../tutorials/websocket-chat.html" > WebSocket Chat</ a ></ li >
< li >< a href = "../tutorials/database-app.html" > Database App</ a ></ li >
< li >< a href = "../tutorials/template-rendering.html" > Templates</ a ></ li >
< li >< a href = "../tutorials/cli-tool.html" > CLI Tool</ a ></ li >
2026-01-25 19:02:02 +01:00
< li >< a href = "../tutorials/web-server.html" > Web Server</ a ></ li >
2026-01-25 13:09:28 +01:00
</ ul >
</ div >
< div class = "section" >
< span class = "section-title" > How-To Guides</ span >
< ul >
< li >< a href = "../howto/index.html" > How-To List</ a ></ li >
< li >< a href = "../howto/http-requests.html" > HTTP Requests</ a ></ li >
< li >< a href = "../howto/json-parsing.html" > JSON Parsing</ a ></ li >
< li >< a href = "../howto/regex-patterns.html" > Regex Patterns</ a ></ li >
< li >< a href = "../howto/file-operations.html" > File Operations</ a ></ li >
< li >< a href = "../howto/async-operations.html" > Async Operations</ a ></ li >
< li >< a href = "../howto/error-handling.html" > Error Handling</ a ></ li >
</ ul >
</ div >
2026-01-25 19:02:02 +01:00
< div class = "section" >
< span class = "section-title" > Contributing</ span >
< ul >
< li >< a href = "../contributing/index.html" > Overview</ a ></ li >
< li >< a href = "../contributing/module-overview.html" > Module Architecture</ a ></ li >
< li >< a href = "../contributing/pure-wren-module.html" > Pure-Wren Modules</ a ></ li >
< li >< a href = "../contributing/c-backed-module.html" > C-Backed Modules</ a ></ li >
< li >< a href = "../contributing/foreign-classes.html" > Foreign Classes</ a ></ li >
< li >< a href = "../contributing/async-patterns.html" > Async Patterns</ a ></ li >
< li >< a href = "../contributing/testing.html" > Writing Tests</ a ></ li >
< li >< a href = "../contributing/documentation.html" > Documentation</ a ></ li >
</ ul >
</ div >
2026-01-25 13:09:28 +01:00
</ nav >
</ aside >
< main class = "content" >
< nav class = "breadcrumb" >
< a href = "../index.html" > Home</ a >
< span class = "separator" > /</ span >
< a href = "index.html" > API Reference</ a >
< span class = "separator" > /</ span >
< span > udp</ span >
</ nav >
< 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 > () → < 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 > () → < 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 > → < 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 > → < 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 > → < span class = "type" > String</ span >
</ div >
< p > The data contained in the message.</ p >
< div class = "method-signature" >
< span class = "method-name" > address</ span > → < span class = "type" > String</ span >
</ div >
< p > The IP address of the sender.</ p >
< div class = "method-signature" >
< span class = "method-name" > port</ span > → < 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 >
</ article >
< footer class = "page-footer" >
< a href = "tls.html" class = "prev" > tls</ a >
< a href = "uuid.html" class = "next" > uuid</ a >
</ footer >
</ main >
</ div >
< script src = "../js/main.js" ></ script >
</ body >
</ html >
