tcpserver — Create a TCP server that listens for MATLAB-compatible client connections.

tcpserver(address, port) creates a TCP/IP listener that waits for clients and exposes MATLAB-compatible properties describing the socket. RunMat mirrors this behaviour: addresses may be IPv4, IPv6, or hostnames, and the function returns a handle-like struct whose fields match MATLAB’s tcpserver object (including ServerAddress, ServerPort, Timeout, UserData, and BytesAvailableFcn metadata). The builtin validates inputs, binds the socket, records configuration, and raises MATLAB-style diagnostics on failure.

How tcpserver works in RunMat

• tcpserver(address, port) binds to the requested interface; pass "0.0.0.0" or "::" to listen on every IPv4 or IPv6 adapter respectively.
• Ports must be in the range 0–65535. Passing 0 requests an ephemeral OS-assigned port that RunMat reports in the returned struct.
• Supported name-value pairs mirror MATLAB defaults: Timeout (non-negative seconds, default 10), UserData (stored verbatim), Name (defaults to "tcpserver:<address>:<port>"), and ByteOrder ("little-endian" or "big-endian"). Unsupported options raise RunMat:tcpserver:InvalidNameValue.
• The returned struct mirrors MATLAB properties, including connection state, callback metadata, and an internal __tcpserver_id identifier that future networking builtins use to locate the listener.
• GPU-resident scalars are gathered automatically before binding so that socket setup always executes on the host CPU.
• Bind failures raise RunMat:tcpserver:BindFailed with the OS-provided error message, preserving MATLAB-style diagnostics.

How tcpserver runs on the GPU

Networking occurs entirely on the host CPU. If the address or port arguments originate on the GPU, RunMat gathers them before binding the socket. The struct returned by tcpserver is always CPU-resident, and acceleration providers do not need to implement any hooks for this builtin.

GPU memory and residency

No. tcpserver is a host-side operation. RunMat transparently gathers GPU scalars before binding the socket, so keeping address or port values on the GPU provides no performance benefit.

Examples

Creating a loopback TCP server on a fixed port

srv = tcpserver("127.0.0.1", 55000);
disp(srv.ServerAddress)
disp(srv.ServerPort)

Expected output:

127.0.0.1
55000

Requesting an ephemeral port and inspecting the assigned value

srv = tcpserver("0.0.0.0", 0);
fprintf("Listening on %s:%d\n", srv.ServerAddress, srv.ServerPort)

Expected output:

Listening on 0.0.0.0:54873   % actual port varies by run

Configuring the timeout and storing metadata in UserData

srv = tcpserver("localhost", 60000, "Timeout", 5, "UserData", struct("name", "demo"));
disp(srv.Timeout)
disp(srv.UserData.name)

Expected output:

5
demo

Assigning a custom server name

srv = tcpserver("::1", 45000, "Name", "LoopbackServer");
disp(srv.Name)

Expected output:

LoopbackServer

Selecting big-endian byte order for binary protocols

srv = tcpserver("127.0.0.1", 45001, "ByteOrder", "big-endian");
disp(srv.ByteOrder)

Expected output:

big-endian

Handling invalid ports with MATLAB-style diagnostics

try
    srv = tcpserver("127.0.0.1", 99999);
catch err
    disp(err.identifier)
    disp(err.message)
end

Expected output:

RunMat:tcpserver:InvalidPort
RunMat:tcpserver:InvalidPort: tcpserver: port 99999 is outside the valid range 0–65535

FAQ

What range of ports can I use?

Valid ports are 0–65535. Port 0 lets the OS choose an available ephemeral port, which RunMat reports in the returned struct.

How do I discover which clients are connected?

The returned struct exposes MATLAB-compatible fields (Connected, ClientAddress, ClientPort). Future networking builtins will use the internal __tcpserver_id to inspect active connections.

Does RunMat support IPv6?

Yes. Pass an IPv6 literal (e.g., "::1") or hostname that resolves to IPv6. The returned ServerAddress reflects the bound address.

Can I change the timeout after creating the server?

Not yet. The current builtin records the timeout value for future builtins. A forthcoming setter will update the listener configuration.

Does tcpserver fire callbacks like MATLAB’s BytesAvailableFcn?

Callback-related properties are present for compatibility, and future updates will allow callers to configure them. They currently act as placeholders while connection management matures.

How do I close the server?

A companion builtin (planned) will accept the returned struct and release the underlying listener. Tests can invoke internal helpers until that builtin lands.

Can I use GPU arrays for address or port?

Yes—RunMat gathers them automatically before binding.

What happens if the port is already in use?

tcpserver raises RunMat:tcpserver:BindFailed with the OS error message.

How do I pass additional socket options?

Current support covers Timeout, Name, UserData, and ByteOrder. Additional name-value options (broadcast, reuse, keep-alive) will land alongside their corresponding provider hooks.

Is TLS supported?

Not directly. Combine tcpserver with application-layer protocol helpers or custom TLS wrappers until dedicated support lands.

Related functions to explore

These functions work well alongside tcpserver. Each page has runnable examples you can try in the browser.

fopen, fread, fwrite, fprintf, accept, close, read, readline, tcpclient, write

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how tcpserver works, line by line, in Rust.

• View tcpserver.rs on GitHub
• Learn how the runtime works
• Found a bug? Open an issue with a minimal reproduction.

About RunMat

RunMat is an open-source runtime that executes MATLAB-syntax code — faster, on any GPU, with no license required.

• Simulations that took hours now take minutes. RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed.
• Start running code in seconds. Open the browser sandbox or download a single binary. No license server, no IT ticket, no setup.
• A full development environment. GPU-accelerated 2D and 3D plotting, automatic versioning on every save, and a browser IDE you can share with a link.

Getting started · Benchmarks · Pricing