RunMat
GitHub

View all functions

CategoryIo: Net

What does the read function do in MATLAB / RunMat?

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 does the read function behave in MATLAB / 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 MATLAB: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 MATLAB:read:InvalidTcpClient, timeouts emit MATLAB:read:Timeout, and connection closures before a requested count is met raise MATLAB:read:ConnectionClosed.

read Function GPU Execution Behaviour

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 of using the read function in MATLAB / RunMat

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 (double row vector):

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:

MATLAB: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 MATLAB: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).

See also

tcpclient, accept, write, readline

Source & feedback