read — Read numeric or text data from a remote host through a MATLAB-compatible tcpclient struct.

read(t) consumes data waiting on the TCP/IP client returned by tcpclient (or accept). The builtin mimics MATLAB’s behaviour for read so existing code that exchanges bytes with remote services behaves identically. It honours the client’s configured Timeout, respects the ByteOrder property when materialising multi-byte numeric types, and interprets the optional datatype argument just like MATLAB.

How read works in RunMat

• data = read(t) waits until at least one byte becomes available (subject to the client timeout) and then drains the socket buffer, returning a **row vector of doubles** whose values come from the received bytes. If the peer closes the connection without sending data, the result is an empty row vector.
• data = read(t, count) blocks until exactly count values are available (again honouring Timeout). When the peer closes the socket before satisfying the request the builtin raises RunMat:read:ConnectionClosed.
• data = read(t, count, datatype) interprets the values using the requested MATLAB datatype. Supported tokens mirror MATLAB: "uint8" (default), "int8", "uint16", "int16", "uint32", "int32", "uint64", "int64", "single", "double", "char", and "string". Numeric outputs are returned as doubles; "char" produces a MATLAB-style character row vector and "string" returns a scalar string.
• Every call honours the client’s ByteOrder property when decoding multi-byte numbers. Little-endian is the default, but "big-endian" is respected for data written in network byte order.
• The builtin gathers GPU-resident arguments automatically, executes the socket read on the CPU, and returns host values.
• Errors are raised with MATLAB-compatible identifiers: invalid client structs trigger RunMat:read:InvalidTcpClient, timeouts emit RunMat:read:Timeout, and connection closures before a requested count is met raise RunMat:read:ConnectionClosed.

How read runs on the GPU

Networking is a host-only subsystem. When a client struct or argument arrives from the GPU, RunMat gathers the value back to the CPU before reading from the socket. No acceleration-provider hooks participate in the operation, and the result is always a host value (double tensor, char array, or string). Future GPU providers continue to gather metadata automatically so networking remains CPU-bound.

Examples

Reading a fixed number of bytes from a TCP echo service

client = tcpclient("127.0.0.1", 50000);
write(client, uint8(1:6));
payload = read(client, 6)

Expected output:

payload =
     1     2     3     4     5     6

Reading ASCII text as characters

client = tcpclient("127.0.0.1", 50001);
write(client, "RunMat TCP");
chars = read(client, 10, "char")

Expected output:

chars =
    'RunMat TCP'

Reading doubles written in big-endian byte order

client = tcpclient("localhost", 50002, "ByteOrder", "big-endian");
write(client, swapbytes([1 2 3], "double"));
values = read(client, 3, "double")

Expected output:

values =
     1     2     3

Reading all available data without specifying a count

client = tcpclient("127.0.0.1", 50003);
write(client, uint8([10 20 30]));
burst = read(client)

Expected output:

burst =
    10    20    30

Handling read timeouts gracefully

client = tcpclient("example.com", 12345, "Timeout", 0.5);
try
    data = read(client, 64);
catch err
    disp(err.identifier)
end

Expected output:

RunMat:read:Timeout

FAQ

Does read modify the client struct?

No. The builtin interacts with the socket stored in RunMat’s internal registry. The visible struct returned from tcpclient is passed by value and is not mutated in place.

What happens when the remote host closes the connection?

If the peer closes the connection before the requested count is satisfied, read raises RunMat:read:ConnectionClosed. When no specific count is requested (read(t)), the builtin returns whatever data was available before the closure (possibly an empty vector).

Does read support infinite timeouts?

Yes. Setting t.Timeout = Inf (or passing "Timeout", inf when constructing the client) leaves the socket in blocking mode. The builtin waits indefinitely until enough data arrives or the peer closes the connection.

How are multibyte integers decoded?

RunMat honours the client’s ByteOrder property ("little-endian" or "big-endian"). For example, read(t, 4, "uint16") consumes eight bytes and interprets each pair in the configured byte order.

Can I read UTF-8 strings directly?

Use the "string" datatype. The builtin converts each received byte directly into a MATLAB string scalar assuming UTF-8 (non-UTF-8 sequences fall back to byte-wise decoding).

Related functions to explore

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

tcpclient, accept, write, readline, close, tcpserver

Open-source implementation

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

• View read.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