std.io.net

TCP for tasks: listen/accept on the server side, connect on the client's, readSome/write on both, every waiting form yielding to the scheduler instead of blocking the thread.

The silent forms answer whether (null/false); the OrThrow twins say why with an IoError, from the same implementation. readSome folds three truths into one answer: bytes are bytes, an EMPTY array is the peer being done (EOF), and null is a failure.

Listener alias

pub type Listener = int

A listening endpoint. Opaque: it is issued here, never assembled.

stdlib/std/io/net.lyr:27

Socket alias

pub type Socket = int

A connected stream. Opaque, like the listener.

stdlib/std/io/net.lyr:30

UdpSocket alias

pub type UdpSocket = int

A UDP endpoint. Opaque, like the others; one handle both sends and receives.

stdlib/std/io/net.lyr:33

Packet struct

pub struct Packet

One received datagram: its payload, and who sent it — the address sendTo answers to.

UDP has no EOF, so an EMPTY payload here is a real (empty) packet, not an end — the one place this module's bytes mean something different than readSome's.

bytes: uint8[]

The payload, complete: a datagram arrives whole or not at all.

host: string

The sender's address, as the receiving socket saw it.

port: int

The sender's port.

stdlib/std/io/net.lyr:39

listen function

pub fn listen(host: string, port: int): ?Listener

Listens on host:port. Port 0 asks the OS for a free one — localPort says which. null when the address cannot be taken; listenOrThrow says why.

stdlib/std/io/net.lyr:89

listenOrThrow function

pub fn listenOrThrow(host: string, port: int): Listener throws IoError

listen, with the reason when it cannot.

stdlib/std/io/net.lyr:98

localPort function

pub fn localPort(listener: Listener): int

The port a listener actually holds — the answer to listen(host, 0).

stdlib/std/io/net.lyr:107

accept function

pub fn accept(listener: Listener): ?Socket

Waits for the next connection. null when the listener broke; acceptOrThrow says why.

stdlib/std/io/net.lyr:112

acceptOrThrow function

pub fn acceptOrThrow(listener: Listener): Socket throws IoError

accept, with the reason when the listener broke.

stdlib/std/io/net.lyr:126

connect function

pub fn connect(host: string, port: int): ?Socket

Waits until a connection to host:port stands or is refused. null on refusal or any other failure; connectOrThrow names the kind — ConnectionRefused when nothing listens.

stdlib/std/io/net.lyr:136

connectOrThrow function

pub fn connectOrThrow(host: string, port: int): Socket throws IoError

connect, with the reason when it cannot.

stdlib/std/io/net.lyr:155

readSome function

pub fn readSome(socket: Socket, max: int): ?uint8[]

Waits for bytes and reads up to max of them. Three truths in one answer: bytes are bytes, an EMPTY array is the peer being done (EOF), and null is a failure — readSomeOrThrow says which failure.

A max of zero or less PANICS: an empty answer already means EOF, so there is no honest value to hand back for it.

stdlib/std/io/net.lyr:169

readSomeOrThrow function

pub fn readSomeOrThrow(socket: Socket, max: int): uint8[] throws IoError

readSome, with the reason when the stream broke. EOF stays the empty array — the peer being done is an ordinary state, not a failure.

stdlib/std/io/net.lyr:187

write function

pub fn write(socket: Socket, bytes: uint8[]): bool

Writes ALL of bytes, waiting whenever the stream is full. false when the stream broke midway; writeOrThrow says why.

stdlib/std/io/net.lyr:197

writeOrThrow function

pub fn writeOrThrow(socket: Socket, bytes: uint8[]): void throws IoError

write, with the reason when the stream broke.

stdlib/std/io/net.lyr:214

close function

pub fn close(socket: Socket): void

Closes a socket. Closing twice closes once.

stdlib/std/io/net.lyr:221

closeListener function

pub fn closeListener(listener: Listener): void

Closes a listener.

stdlib/std/io/net.lyr:226

bind function

pub fn bind(host: string, port: int): ?UdpSocket

Binds a UDP endpoint on host:port. Port 0 asks the OS for a free one — localPort says which. null when the address cannot be taken; bindOrThrow says why, AddressInUse being the usual answer.

stdlib/std/io/net.lyr:235

bindOrThrow function

pub fn bindOrThrow(host: string, port: int): UdpSocket throws IoError

bind, with the reason when it cannot.

stdlib/std/io/net.lyr:244

localPort function

pub fn localPort(socket: UdpSocket): int

The port a UDP endpoint actually holds — the answer to bind(host, 0).

stdlib/std/io/net.lyr:253

sendTo function

pub fn sendTo(socket: UdpSocket, host: string, port: int, bytes: uint8[]): bool

Sends one datagram to host:port, waiting out a full send buffer. The datagram goes whole or not at all; false when it cannot go — sendToOrThrow says why. There is no delivery promise: that is UDP, not this module.

stdlib/std/io/net.lyr:260

sendToOrThrow function

pub fn sendToOrThrow(socket: UdpSocket, host: string, port: int, bytes: uint8[]): void throws IoError

sendTo, with the reason when the datagram cannot go.

stdlib/std/io/net.lyr:274

receiveFrom function

pub fn receiveFrom(socket: UdpSocket, max: int): ?Packet

Waits for one datagram and answers it whole, with its sender. A payload longer than max is CUT to it — datagrams do not queue their remainder. null is a failure; receiveFromOrThrow says which. An empty payload is a real packet: UDP has no EOF.

A max of zero or less PANICS. It would otherwise cut the datagram to one byte and throw the rest away, which is the cutting rule above turned into silent data loss.

stdlib/std/io/net.lyr:291

receiveFromOrThrow function

pub fn receiveFromOrThrow(socket: UdpSocket, max: int): Packet throws IoError

receiveFrom, with the reason when the socket broke.

stdlib/std/io/net.lyr:308

close function

pub fn close(socket: UdpSocket): void

Closes a UDP endpoint. Closing twice closes once.

stdlib/std/io/net.lyr:317