read — Read bytes or typed values from a tcpclient connection with MATLAB-compatible behavior.
read(t) consumes data waiting on the TCP/IP client returned by tcpclient (or accept). It follows MATLAB behavior for timeout handling, byte-order decoding, and optional datatype conversion so networking code ports directly.
Syntax
data = read(client)
data = read(client, count)
data = read(client, count, datatype)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
client | Any | Yes | — | tcpclient handle struct. |
count | NumericScalar | Yes | — | Requested element count. |
datatype | StringScalar | No | "uint8" | Data type label (for example "uint8", "double", "char", "string"). |
Returns
| Name | Type | Description |
|---|---|---|
data | Any | Available bytes or requested typed payload from the TCP client. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:read:InvalidTcpClient | Client handle is missing, malformed, invalid, or disconnected. | read: invalid tcpclient handle |
RunMat:read:InvalidInput | Argument list shape is unsupported for read. | read: invalid argument list |
RunMat:read:NotConnected | Client has no active socket connection. | read: tcpclient is disconnected |
RunMat:read:Timeout | Socket read exceeds configured timeout. | read: timed out waiting for data |
RunMat:read:ConnectionClosed | Peer closes socket before requested payload is fully available. | read: connection closed before the requested data was received |
RunMat:read:InvalidCount | Requested count is non-scalar, negative, non-finite, or out of range. | read: invalid count argument |
RunMat:read:InvalidDataType | Datatype argument is not a supported scalar text label. | read: invalid datatype argument |
RunMat:read:InternalError | Internal socket/control-flow conversion fails. | read: internal socket error |
How read works
data = read(t)waits until at least one byte becomes available (subject to the client timeout) and then drains the socket buffer, returning a rowuint8vector. If the peer closes the connection without sending data, the result is an emptyuint8row vector.data = read(t, count)blocks until exactlycountuint8values are available (again honouringTimeout). The count may use any native integer class and is read exactly; when the peer closes the socket before satisfying the request the builtin raisesRunMat:read:ConnectionClosed.data = read(t, count, datatype)interprets the values using the requested MATLAB datatype. Supported tokens are"uint8"(default),"int8","uint16","int16","uint32","int32","uint64","int64","single","double","char", and"string". Numeric results retain the requested native class, including exact 64-bit integer values and physical single precision;"char"produces a character row vector and"string"returns a scalar string.- Every call honours the client’s
ByteOrderproperty 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 emitRunMat:read:Timeout, and connection closures before a requested count is met raiseRunMat:read:ConnectionClosed.
Does RunMat run read on the GPU?
Networking is a host-only subsystem. Resident client metadata or count arguments gather transparently before socket I/O. No acceleration-provider hook participates, and the result is always a host value in its selected native numeric class, a character array, or a string.
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 6Reading 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 3Reading 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 30Handling read timeouts gracefully
client = tcpclient("example.com", 12345, "Timeout", 0.5);
try
data = read(client, 64);
catch err
disp(err.identifier)
endExpected output:
RunMat:read:TimeoutUsing read with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how read changes the result.
Run a small read example, explain the result, then change one input and compare the output.
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 Io functions
Repl Fs
addpath · cd · copyfile · delete · dir · exist · fileattrib · fileparts · fullfile · genpath · getenv · getpref · isenv · isfile · isfolder · ispref · ls · matlabroot · memmapfile · mkdir · movefile · open · opentoline · path · pathsep · pcode · pwd · readstruct · rehash · restoredefaultpath · rmdir · rmpath · run · savepath · setenv · setpref · system · tempdir · tempname · uigetdir · uigetfile · uiputfile · unsetenv · userpath · what · winqueryreg · xmlread · xmlwrite
Tabular
arrayDatastore · csvread · csvwrite · detectImportOptions · dlmread · dlmwrite · fileDatastore · parquetDatastore · parquetinfo · parquetread · readcell · readmatrix · readtable · readtimetable · spreadsheetImportOptions · writecell · writematrix · writetable · writetimetable · xlsread · xlswrite
Filetext
fclose · feof · fgetl · fgets · fileread · filewrite · fopen · fprintf · fread · frewind · fwrite · readlines · writelines
Import
Json
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how read is executed, line by line, in Rust.
- View the source for read in Rust on GitHub
- Learn how the RunMat 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 blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.