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.

stdlib/std/io/net.lyr:166

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:181

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:191

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:208

close function

pub fn close(socket: Socket): void

Closes a socket. Closing twice closes once.

stdlib/std/io/net.lyr:215

closeListener function

pub fn closeListener(listener: Listener): void

Closes a listener.

stdlib/std/io/net.lyr:220

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:229

bindOrThrow function

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

bind, with the reason when it cannot.

stdlib/std/io/net.lyr:238

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:247

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:254

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:268

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.

stdlib/std/io/net.lyr:282

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:296

close function

pub fn close(socket: UdpSocket): void

Closes a UDP endpoint. Closing twice closes once.

stdlib/std/io/net.lyr:305