RunMat
GitHub

View all functions

CategoryIo: Net

What does the readline function do in MATLAB / RunMat?

readline(t) reads ASCII text from the remote host associated with the MATLAB-compatible tcpclient struct t. It consumes data until it encounters the line terminator (RunMat currently honours the MATLAB default line feed (LF, "\n")) and returns the characters without the terminator. If the terminator is not observed before the timeout elapses, the builtin returns a 0-by-0 double ([]) just like MATLAB and preserves the buffered bytes for the next call. When the peer closes the connection, any buffered characters are returned and the internal connection flag is cleared.

How does the readline function behave in MATLAB / RunMat?

  • readline(t) waits for data and reads character bytes until the first line feed. The returned value is a MATLAB string scalar that excludes the terminator, mirroring MATLAB’s tcpclient.readline.
  • If the peer uses carriage-return/line-feed pairs ("\r\n"), RunMat automatically strips both bytes so the returned string matches MATLAB’s behaviour for default CR/LF terminators.
  • When the terminator is not encountered before the client’s Timeout expires, the builtin returns a 0-by-0 double ([]). Any bytes that arrived remain buffered internally so the next readline call continues assembling the same logical line.
  • If the remote host closes the connection before a terminator is observed, the builtin returns the buffered characters (which might be empty) and marks the underlying client as disconnected so subsequent network calls can react accordingly.
  • Inputs passed from the GPU are gathered automatically. Networking always runs on the CPU and the returned string is CPU-resident.
  • Invalid structs, missing handles, or disconnected clients raise MATLAB-style diagnostics (for example, MATLAB:readline:InvalidTcpClient).

readline Function GPU Execution Behaviour

Networking is exclusively a host-side activity. When a tcpclient struct resides on the GPU, RunMat gathers it back to the CPU before touching the socket. Acceleration providers are not consulted and no GPU buffers are produced. Future GPU-aware networking features will continue to gather metadata automatically so sockets remain purely CPU-bound.

Examples of using the readline function in MATLAB / RunMat

Reading a newline-terminated response from an echo server

client = tcpclient("127.0.0.1", 55000);
write(client, "ping\n");
reply = readline(client);

Expected output:

reply = "ping"

Handling CRLF-terminated lines from legacy services

client = tcpclient("legacy.example.com", 1600);
write(client, "HELLO\r\n");
line = readline(client);  % CRLF is removed automatically

Expected output:

line = "OK HELLO"

Looping over streaming telemetry one line at a time

client = tcpclient("telemetry.example.com", 9000, "Timeout", 5);
while true
    payload = readline(client);
    if isequal(payload, [])
        continue   % timeout, try again once more data arrives
    end
    disp(payload)
end

Detecting closed connections without losing buffered text

client = tcpclient("sensor.example.com", 7000);
try
    line = readline(client);        % returns partial line if peer closed without LF
    disp(line)
    readline(client);               % second call raises MATLAB:readline:NotConnected
catch err
    if err.identifier == "MATLAB:readline:NotConnected"
        disp("Sensor disconnected")
    else
        rethrow(err)
    end
end

Responding gracefully to quiet periods with finite timeouts

client = tcpclient("chat.example.com", 4040, "Timeout", 0.5);
msg = readline(client);    % returns [] when no line arrives within 0.5 s
if isequal(msg, [])
    disp("No complete chat messages yet.")
end

Parsing numeric payloads that arrive as text lines

client = tcpclient("metrics.example.com", 5050);
line = readline(client);
values = str2double(split(line, ","));  % convert comma-separated numbers

Logging line-delimited JSON messages from a service

client = tcpclient("json.example.com", 6000);
while true
    payload = readline(client);
    if isequal(payload, [])
        break
    end
    decoded = jsondecode(payload);
    disp(decoded.status)
end

GPU residency in RunMat (Do I need gpuArray?)

No. RunMat automatically gathers GPU-resident structs before reading from sockets. The returned string lives on the CPU and there is no benefit to calling gpuArray for networking builtins such as readline.

FAQ

  • Which terminator does RunMat use? RunMat currently honours MATLAB’s default line feed (LF, "\n"). Support for configureTerminator will allow other terminators in a future update.
  • Does readline return the terminator? No. The terminator bytes are stripped and the MATLAB string contains only the payload characters.
  • What happens on timeout? If the terminator is not observed before the configured Timeout, the builtin returns a 0-by-0 double ([]) and retains any buffered bytes so the next call can complete the line once the terminator arrives.
  • How are CR/LF pairs handled? When the payload ends with "\r\n", both bytes are removed so the result matches MATLAB’s CR/LF behaviour.
  • What if the connection closes mid-line? Any buffered text is returned and subsequent calls raise MATLAB:readline:NotConnected, signalling that the socket closed.
  • Does the builtin perform Unicode validation? Bytes are decoded using UTF-8. Invalid sequences fall back to lossless byte-to-char mapping so no data is lost.
  • Can I call readline after gathering a GPU tensor? Yes. readline gathers arguments automatically and always returns host values.
  • Will future GPU providers change the return type? No. Networking results remain CPU strings even when GPUs are available.

See Also

tcpclient, accept, read, write

Source & Feedback