RunMat
GitHub

View all functions

CategoryIo: Net

What does the write function do in MATLAB / RunMat?

write(t, data) transmits binary or textual data over the TCP/IP client returned by tcpclient (or accept). The builtin mirrors MATLAB’s write behaviour so existing socket code continues working without modification. It honours the client’s configured Timeout, applies the ByteOrder property when encoding multi-byte values, and accepts the optional datatype argument used throughout MATLAB’s I/O APIs.

How does the write function behave in MATLAB / RunMat?

  • write(t, data) converts data to unsigned 8-bit integers (the MATLAB default) and sends the bytes to the peer. The return value is the number of elements written when the caller requests an output argument.
  • write(t, data, datatype) encodes the payload using the supplied MATLAB datatype token. Supported values mirror MATLAB: "uint8" (default), "int8", "uint16", "int16", "uint32", "int32", "uint64", "int64", "single", "double", "char", and "string". Numeric conversions saturate to the destination range just like MATLAB cast operations. "char" treats values as single-byte character codes and "string" encodes UTF-8 text.
  • The client’s ByteOrder property controls how multi-byte numeric values are serialised. "little-endian" is the default, while "big-endian" matches the traditional network byte order.
  • When the socket cannot send the entire payload before the timeout expires, write raises MATLAB:write:Timeout. If the peer closes the connection before or during the transfer the builtin raises MATLAB:write:ConnectionClosed and marks the client as disconnected.
  • Inputs that originate on the GPU are gathered back to the host automatically before any bytes are written.

write Function GPU Execution Behaviour

Networking occurs on the host CPU. If data or the tcpclient struct resides on the GPU, RunMat gathers the values to host memory before converting them to bytes. Acceleration providers are not involved and the resulting payload remains on the CPU. Providers that support residency tracking automatically mark any gathered tensors as released.

Examples of using the write function in MATLAB / RunMat

Sending an array of bytes to an echo service

client = tcpclient("127.0.0.1", 50000);
count = write(client, uint8(1:4));

Expected output when an output argument is requested:

count =
     4

Writing doubles with explicit byte order

client = tcpclient("localhost", 50001, "ByteOrder", "big-endian");
values = [1.5 2.5 3.5];
write(client, values, "double");

The remote peer receives 24 bytes representing the doubles in big-endian order.

Transmitting ASCII text

client = tcpclient("127.0.0.1", 50002);
write(client, "RunMat TCP", "char");

Expected payload (one byte per character):

52 117 110 77 97 116 32 84 67 80

Sending UTF-8 encoded strings

client = tcpclient("127.0.0.1", 50003);
write(client, "Διακριτό", "string");

The builtin encodes the Unicode text as UTF-8 before sending it across the socket.

Handling connection closures

client = tcpclient("example.com", 12345, "Timeout", 0.25);
try
    write(client, uint8([1 2 3 4]));
catch err
    disp(err.identifier)
end

Expected output when the peer closes the connection abruptly:

MATLAB:write:ConnectionClosed

FAQ

How many output values does write return?

When the caller requests an output, the builtin returns the number of elements written (after datatype conversion). This mirrors the behaviour of MATLAB’s numeric I/O routines. If no output is requested, the value is discarded.

Does write support complex numbers?

No. The input must be real. Pass separate real and imaginary parts or convert to a byte representation manually.

How are values rounded when converting to integer datatypes?

Floating-point inputs are rounded to the nearest integer and then saturated to the target range, matching MATLAB casts (for example uint8(255.7) becomes 256 → 255, int8(-128.2) becomes -128).

What happens to GPU-resident tensors?

They are gathered automatically before the write. Networking is a CPU-only subsystem, so the resulting data is sent from host memory and any temporary handles are released after the transfer.

Can I stream large payloads?

Yes. write loops until the entire payload has been sent or an error occurs. Large payloads honour the client’s timeout and byte-order settings.

See also

tcpclient, accept, read, readline

Source & feedback