Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-std

Source of release 0.7.5

0.7.5 / src / net / datagram.lucb

#==============================================================================================
#
#   datagram - A UDP socket
#
#   DESCRIPTION:
#       An owned UDP socket: bind, send to and receive from addresses, socket options and
#       readiness waiting.
#
#==============================================================================================

## One owned UDP socket. Zero is closed. Copying does not duplicate ownership;
## copies must not be independently closed. Synchronize calls on one owner.
pub struct Datagram:
    var socket: SocketHandle
    var version: IpVersion

    ## IPv6 sockets are IPv6-only by default. Set ipv6_only=false to permit
    ## mapped IPv4 packets; it has no effect when binding an IPv4 address.
    pub static func bind(address: SocketAddress, ipv6_only: bool = true) -> Datagram!:
        var raw: NativeAddress
        let length = try address.write_native(&raw)
        var acquired = try SocketHandle.create(datagram, address.ip.kind)
        errdefer acquired.destroy()
        let fd = try acquired.require()
        if address.ip.kind == IpVersion.ipv6:
            try set_socket_integer(fd, ipv6_level, ipv6_only_option, 1 if ipv6_only else 0)
        if bind(fd, &raw, length) != 0:
            error(socket_error(socket_errno()), "the datagram socket could not bind its address")
        return Datagram(socket = acquired, version = address.ip.kind)

    ## Query the bound endpoint, including an automatically assigned port.
    pub func address() -> SocketAddress!:
        return try socket_address(try self.socket.require())

    ## Send one complete IP datagram, including an empty packet. A successful
    ## send confirms local acceptance, not peer delivery. IPv4 permits up to 65507
    ## payload bytes, IPv6 up to 65527; host/path limits may be smaller. IPv6
    ## jumbograms are not supported. The destination must match the socket version.
    pub func send_to(data: const u8[], address: SocketAddress) -> !:
        let descriptor = try self.socket.require()
        if address.ip.kind != self.version:
            error(invalid_options, "the datagram destination has a different IP version")
        let maximum: usize = 65507 if self.version == IpVersion.ipv4 else 65527
        if data.length > maximum:
            error(message_too_large, "the UDP payload exceeds the IP version's maximum")
        var raw: NativeAddress
        let length = try address.write_native(&raw)
        var n = sendto(descriptor, data.data, data.length, 0, &raw, length)
        while n < 0 and socket_errno() == socket_interrupted:
            n = sendto(descriptor, data.data, data.length, 0, &raw, length)
        if n < 0:
            error(socket_error(socket_errno()), "the datagram could not be sent")
        if (usize)n != data.length:
            error(failed, "the datagram send did not confirm the complete packet")

    ## Consume one packet. Zero means a valid empty datagram, not stream EOF.
    ## If storage is too small, consume/discard the packet and report
    ## message_too_large; a copied prefix may remain in the buffer. The next call
    ## receives the next packet. Empty storage can receive only an empty packet.
    pub func receive_from(buffer: u8[]) -> (usize, SocketAddress)!:
        let descriptor = try self.socket.require()
        if platform.windows:
            return try windows_receive(descriptor, buffer)
        else:
            var raw: NativeAddress
            # macOS can return immediately without consuming a packet when receive
            # capacity is zero. Probe into one scratch byte so even empty storage
            # consumes exactly one packet and obtains its sender address.
            var scratch: u8[1]
            var vector = ReceiveVector(data = buffer.data, length = buffer.length)
            if buffer.length == 0:
                vector = ReceiveVector(data = &scratch[0], length = 1)
            while true:
                var received: isize = 0
                var address_length: u32 = 0
                var flags: i32 = 0
                if platform.macos:
                    var message = MacMessage(address = &raw, address_length = 28, vectors = &vector, vector_count = 1)
                    received = receive_message_macos(descriptor, &message, 0)
                    address_length = message.address_length
                    flags = message.flags
                else:
                    var message = LinuxMessage(address = &raw, address_length = 28, vectors = &vector, vector_count = 1)
                    received = receive_message_linux(descriptor, &message, 0)
                    address_length = message.address_length
                    flags = message.flags
                if received < 0:
                    let number = socket_errno()
                    if number == socket_interrupted:
                        continue
                    error(socket_error(number), "the datagram could not be received")
                let truncated: i32 = 16 if platform.macos else 32
                if (flags & truncated) != 0 or (usize)received > buffer.length:
                    error(message_too_large, "the receive buffer was too small for the datagram")
                if address_length > 28:
                    error(failed, "the datagram sender address exceeds the supported storage")
                return ((usize)received, try decode_address(&raw, address_length))

    ## Wait for advisory readiness without allocating. Expiration reports timed_out;
    ## cancellation reports cancelled. Use nonblocking I/O after readiness because
    ## another user can consume it. The socket remains borrowed and open.
    pub func wait(interest: WaitInterest = WaitInterest.read, deadline: Deadline = Deadline(), cancellation: sync.Cancellation*? = none) -> Readiness!:
        return try wait_socket(try self.socket.require(), interest, deadline, cancellation)

    ## Change O_NONBLOCK without changing other status flags. Descriptor aliases
    ## share this setting; synchronize changes with all users of this socket.
    pub func set_nonblocking(enabled: bool) -> !:
        try set_nonblocking(try self.socket.require(), enabled)
        self.socket.nonblocking = enabled

    ## Whether the socket is in nonblocking mode.
    pub func is_nonblocking() -> bool!:
        if platform.windows:
            _ = try self.socket.require()
            return self.socket.nonblocking
        else:
            return (try socket_status_flags(try self.socket.require()) & nonblocking_flag) != 0

    ## Request kernel buffering in bytes, not a guaranteed transfer size. The OS
    ## may cap or round the request; receive_buffer returns its reported setting.
    pub func set_receive_buffer(bytes: i32) -> !:
        try set_socket_buffer(try self.socket.require(), receive_buffer_option, bytes)

    ## The receive buffer size in bytes.
    pub func receive_buffer() -> i32!:
        return try get_socket_integer(try self.socket.require(), socket_level, receive_buffer_option)

    ## Request kernel buffering in bytes. Linux reports a doubled bookkeeping
    ## size; both hosts may adjust the request. This does not change user buffers.
    pub func set_send_buffer(bytes: i32) -> !:
        try set_socket_buffer(try self.socket.require(), send_buffer_option, bytes)

    ## The send buffer size in bytes.
    pub func send_buffer() -> i32!:
        return try get_socket_integer(try self.socket.require(), socket_level, send_buffer_option)

    ## Borrow the descriptor; the caller must not close it or retain it past this owner.
    pub func descriptor() -> platform.SocketDescriptor?:
        return self.socket.value

    ## Consume ownership before the OS call. Repeated close is safe even after failure.
    pub func close() -> !:
        try self.socket.close()

    ## Best-effort cleanup for unwinding; use close to observe delayed errors.
    pub func destroy():
        self.socket.destroy()