let pub @socket: Socket

The raw Socket wrapped by this UdpSocket.

fn pub static new(ip: ref IpAddress, port: Int) -> Result[UdpSocket, Error] {
  let socket = try Socket.datagram(ip.v6?)

  try socket.bind(ip, port)
  Result.Ok(UdpSocket(socket))
}

fn pub static new(ip: ref IpAddress, port: Int) -> Result[UdpSocket, Error]

Creates a new UdpSocket, bound to the given address.

Examples

Creating a new bound UDP socket:

import std.net.socket (UdpSocket)
import std.net.ip (IpAddress)

UdpSocket.new(IpAddress.v4(0, 0, 0, 0), port: 0).get

fn pub mut connect(ip: ref IpAddress, port: Int) -> Result[Nil, Error] {
  @socket.connect(ip, port)
}

fn pub mut connect(ip: ref IpAddress, port: Int) -> Result[Nil, Error]

Connects self to the remote address.

Connecting a UdpSocket allows sending and receiving data using the methods from std.io.Read and std.io.Write, instead of having to use UdpSocket.receive_from and UdpSocket.send_to.

Examples

Connecting a UDP socket:

import std.net.socket (UdpSocket)
import std.net.ip (IpAddress)

let socket1 =
  UdpSocket.new(ip: IpAddress.v4(0, 0, 0, 0), port: 40_000).get
let socket2 =
  UdpSocket.new(ip: IpAddress.v4(0, 0, 0, 0), port: 41_000).get

socket1.connect(ip: IpAddress.v4(0, 0, 0, 0), port: 41_000).get

fn pub mut flush -> Result[Nil, Never] {
  Result.Ok(nil)
}

fn pub mut flush -> Result[Nil, Never]

Flushes any pending writes to the file system.

Flushing writes is a potentially expensive operation, and unnecessarily calling this method may degrade performance.

When flushing data to disk it's important to remember that the actual behaviour may vary based on the type of file system, operating system and storage hardware that's used. In particular, it's possible for one of these components to say "Yup, I totally flushed the data, you're all good!" when in fact they have not fully flushed the data.

fn pub local_address -> Result[SocketAddress, Error] {
  @socket.local_address
}

fn pub local_address -> Result[SocketAddress, Error]

Returns the local address of this socket.

See the documentation of Socket.local_address for more information.

fn pub mut print(string: String) -> Result[Nil, Error] {
  write_string(string).then(fn (_) { write_string('\n') })
}

fn pub mut print(string: String) -> Result[Nil, Error]

Writes the entirety of string to the underlying stream, followed by writing a Unix newline to the stream.

fn pub mut read(into: mut ByteArray, size: Int) -> Result[Int, Error] {
  @socket.read(into, size)
}

fn pub mut read(into: mut ByteArray, size: Int) -> Result[Int, Error]

Reads up to size bytes from self into the given ByteArray, returning the number of bytes read.

The into argument is the ByteArray to read the bytes into. The capacity of this ByteArray is increased automatically if necessary.

The size argument specifies how many bytes are to be read.

The return value is the number of bytes read.

The number of bytes read may be less than size. This can happen for different reasons, such as when all input is consumed or not enough data is available (yet).

fn pub mut read_all(bytes: mut ByteArray) -> Result[Int, Error] {
  let mut total = 0
  let mut read_size = INITIAL_READ_ALL_SIZE

  loop {
    match read(into: bytes, size: read_size) {
      case Ok(0) -> return Result.Ok(total)
      case Ok(n) -> {
        total += n

        # To reduce the number of calls to `Reader.read` when there's lots of
        # input to consume, we increase the read size if deemed beneficial.
        if read_size < MAX_READ_ALL_SIZE and n == read_size { read_size *= 2 }
      }
      case Error(e) -> throw e
    }
  }
}

fn pub mut read_all(bytes: mut ByteArray) -> Result[Int, Error]

Reads from self into the given ByteArray, returning when all input is consumed.

The return value is the number of bytes read.

Errors

This method returns an Error if the underlying call to Read.read returns an Error.

fn pub mut read_exact(into: mut ByteArray, size: Int) -> Result[Nil, Error] {
  let mut pending = size

  while pending > 0 {
    match read(into, pending) {
      case Ok(0) if pending > 0 -> throw Error.EndOfInput
      case Ok(n) -> pending -= n
      case Error(e) -> throw e
    }
  }

  Result.Ok(nil)
}

fn pub mut read_exact(into: mut ByteArray, size: Int) -> Result[Nil, Error]

Reads exactly size bytes into into.

Whereas Read.read might return early if fewer bytes are available in the input stream, Read.read_exact continues reading until the desired amount of bytes is read.

Errors

If the end of the input stream is encountered before filling the buffer, an Error.EndOfInput error is returned.

If an error is returned, no assumption can be made about the state of the into buffer, i.e. there's no guarantee data read so far is in the buffer in the event of an error.

fn pub mut receive_from(
  bytes: mut ByteArray,
  size: Int,
) -> Result[(Int, SocketAddress), Error] {
  @socket.receive_from(bytes, size)
}

fn pub mut receive_from(bytes: mut ByteArray, size: Int) -> Result[(Int, SocketAddress), Error]

Receives a single datagram message on the socket, returning the size of the message and the address the message was sent from.

See the documentation of Socket.receive_from for more information.

fn pub mut send_bytes_to(
  bytes: ref ByteArray,
  ip: ref IpAddress,
  port: Int,
) -> Result[Int, Error] {
  @socket.send_bytes_to(bytes, ip, port)
}

fn pub mut send_bytes_to(bytes: ref ByteArray, ip: ref IpAddress, port: Int) -> Result[Int, Error]

Sends a ByteArray to the given address.

See the documentation of Socket.send_bytes_to for more information.

Examples

import std.net.socket (UdpSocket)
import std.net.ip (IpAddress)

let socket =
  UdpSocket.new(ip: IpAddress.v4(0, 0, 0, 0), port: 9999).get
let bytes = 'hello'.to_byte_array

socket
  .send_bytes_to(
    bytes: bytes,
    ip: IpAddress.v4(0, 0, 0, 0),
    port: 9999
  )
  .get

fn pub mut send_string_to(
  string: String,
  ip: ref IpAddress,
  port: Int,
) -> Result[Int, Error] {
  @socket.send_string_to(string, ip, port)
}

fn pub mut send_string_to(string: String, ip: ref IpAddress, port: Int) -> Result[Int, Error]

Sends a String to the given address.

See the documentation of Socket.send_string_to for more information.

Examples

import std.net.socket (UdpSocket)
import std.net.ip (IpAddress)

let socket =
  UdpSocket.new(ip: IpAddress.v4(0, 0, 0, 0), port: 9999).get

socket
  .send_string_to(
    string: 'hello',
    ip: IpAddress.v4(0, 0, 0, 0),
    port: 9999
  )
  .get

fn pub try_clone -> Result[UdpSocket, Error] {
  @socket.try_clone.map(fn (sock) { UdpSocket(sock) })
}

fn pub try_clone -> Result[UdpSocket, Error]

Attempts to clone the socket.

Cloning a socket may fail, such as when the program has too many open file descriptors.

fn pub mut write_bytes(bytes: ref ByteArray) -> Result[Nil, Error] {
  @socket.write_bytes(bytes)
}

fn pub mut write_bytes(bytes: ref ByteArray) -> Result[Nil, Error]

Writes the entirety of bytes to the underlying stream.

Types implementing this method must guarantee that upon returning from this method, either all of the data is written and a Ok(Nil) is returned, or an Error(Error) is returned.

fn pub mut write_string(string: String) -> Result[Nil, Error] {
  @socket.write_string(string)
}

fn pub mut write_string(string: String) -> Result[Nil, Error]

Writes the entirety of string to the underlying stream.

See Write.write_bytes for more details.