Standard Library

class TcpListener

A listening socket that delivers each incoming connection as a TcpStream.

since 0.1.0-alpha.1linux

Overview

Create it with the port to listen on, check ok, and call connections with a function that receives every new client. The listener listens on the local loopback address of the machine. The program keeps running while a listener is active; stop ends it.

Description

TcpListener(port) starts listening on a local port. It is a stream of connections: connections(callback) registers a callback that receives a new TcpStream for every client that connects. The listener accepts every connection waiting at the moment it is woken, so a burst of clients is handled in one pass.

• ok() is true when the port was opened. It is false if the port is in use or could not be bound; check it before relying on the listener.
• connections(callback) begins accepting. The program is now waiting on the listener and does not exit while it is open (see lang.event-loop).
• stop() stops accepting and closes the listening socket. It is idempotent, and a stopped listener does nothing if stop() is called again.

The listener binds on the loopback interface and takes only a port number.

Rules

• Check ok() after constructing a listener.
• A listener keeps the program alive until stop() is called.
• Each accepted TcpStream is yours: set its onData and onClose callbacks, and let it close when the client leaves, or close it yourself.
• The accept callback runs on the event loop and never concurrently with other callbacks.

Examples

An echo server that stops after a minute:

TcpListener listener = TcpListener(8080);
if (!listener.ok()) {
    console.writeln("port 8080 is not available");
} else {
    listener.connections((conn) => {
        conn.onData((chunk) => conn << "echo: " << chunk);
        conn.onClose(() => console.writeln("client left"));
    });
    std::sysTimerStart(60000, 0, (n) => listener.stop());
}

Notes

HttpServer wraps a TcpListener and handles the HTTP framing; use it for web servers.

Examples

An echo server

TcpListener listener = TcpListener(8080);
if (!listener.ok()) {
    console.writeln("port 8080 is not available");
} else {
    listener.connections((TcpStream client) => {
        client.onData((chunk) => { client << chunk; });
    });
}

Constructors

new

new(int port)

Start listening on a port.

If the port cannot be opened, for example because it is already in use, the listener is created anyway and ok returns false.

Parameters

port

The port number to listen on.

Methods

connections

connections((TcpStream) => void cb) -> void

Deliver every incoming connection to a function.

The function is called once per client, on the event loop, with a TcpStream for that client. Connections that arrive together are all delivered.

Parameters

cb

The function that receives each new client.

ok

ok() -> bool

Tell whether the listener is open.

Returns

true when the port was opened and the listener has not been stopped.

stop

stop() -> void

Stop listening and close the port.

Calling it more than once does nothing. Connections that were already accepted are not affected.

See also

• TcpStream — A connected network socket that reads and writes text.
• HttpServer — A web server that listens on a port and answers each request with a handler function.