{
"title": "accept",
"category": "io/net",
"keywords": [
"accept",
"tcpserver",
"tcpclient",
"socket",
"networking"
],
"summary": "Accept a pending client connection on a TCP server.",
"references": [
"https://www.mathworks.com/help/matlab/ref/accept.html"
],
"gpu_support": {
"elementwise": false,
"reduction": false,
"precisions": [],
"broadcasting": "none",
"notes": "Networking runs on the host CPU. GPU-resident metadata is gathered automatically before accepting connections."
},
"fusion": {
"elementwise": false,
"reduction": false,
"max_inputs": 2,
"constants": "inline"
},
"requires_feature": null,
"tested": {
"unit": "builtins::io::net::accept::tests",
"integration": "builtins::io::net::accept::tests::accept_establishes_client_connection"
},
"description": "`accept(server)` waits for a pending TCP connection on the socket created by `tcpserver`. When a client connects, the builtin returns a MATLAB-compatible struct that mirrors the `tcpclient` object. The struct tracks connection metadata (remote address, port, byte order, and timeout settings) and holds an opaque identifier that other RunMat networking builtins use to operate on the live socket.",
"behaviors": [
"The first argument must be the struct returned from `tcpserver`. RunMat validates that the struct contains a `__tcpserver_id` field and raises `RunMat:accept:InvalidTcpServer` when the identifier is missing or no longer points to an active listener.",
"By default, `accept` uses the timeout configured when the server was created (`Timeout` name-value pair on `tcpserver`). You can override it per call with `accept(server, \"Timeout\", seconds)`. The timeout must be non-negative; the builtin raises `RunMat:accept:InvalidNameValue` when the value is NaN, negative, or non-scalar.",
"Successful calls return immediately with a struct whose fields mirror MATLAB’s `tcpclient` properties (`Address`, `Port`, `NumBytesAvailable`, `BytesAvailableFcn`, `ByteOrder`, `Timeout`, `UserData`, and `Connected`). The struct also contains hidden fields `__tcpserver_id` and `__tcpclient_id` so higher-level builtins can operate on the live socket.",
"If no client connects before the timeout expires, the builtin raises `RunMat:accept:Timeout`.",
"When the underlying OS reports an accept failure (for example, because the socket closed), the builtin raises `RunMat:accept:AcceptFailed` with the platform error message.",
"Networking occurs on the host CPU. If the server struct or timeout value lives on the GPU, RunMat gathers it to the host automatically before waiting for connections."
],
"examples": [
{
"description": "Accepting a localhost client connection",
"input": "srv = tcpserver(\"127.0.0.1\", 0);\nport = srv.ServerPort;\ntcpclient(\"127.0.0.1\", port);\nclient = accept(srv);\ndisp(client.Address)\ndisp(client.Port)",
"output": "127.0.0.1\n55000 % varies per run"
},
{
"description": "Overriding the timeout for a single accept call",
"input": "srv = tcpserver(\"0.0.0.0\", 0, \"Timeout\", 10);\ntry\n client = accept(srv, \"Timeout\", 0.25);\ncatch err\n disp(err.identifier)\nend",
"output": "RunMat:accept:Timeout"
},
{
"description": "Inspecting connection metadata after accepting a client",
"input": "srv = tcpserver(\"::1\", 45000);\ntcpclient(\"::1\", 45000);\nclient = accept(srv);\nfprintf(\"Remote peer %s:%d\\\\n\", client.Address, client.Port);\nfprintf(\"Byte order: %s\\\\n\", client.ByteOrder)",
"output": "Remote peer ::1:51432\nByte order: little-endian"
},
{
"description": "Handling multiple queued clients sequentially",
"input": "srv = tcpserver(\"127.0.0.1\", 47000);\ntcpclient(\"127.0.0.1\", 47000);\ntcpclient(\"127.0.0.1\", 47000);\nclient1 = accept(srv);\nclient2 = accept(srv);\nfprintf(\"First connection from %s\\\\n\", client1.Address);\nfprintf(\"Second connection from %s\\\\n\", client2.Address)",
"output": "First connection from 127.0.0.1\nSecond connection from 127.0.0.1"
},
{
"description": "Using the returned identifier with other networking builtins",
"input": "srv = tcpserver(\"127.0.0.1\", 52000);\ntcpclient(\"127.0.0.1\", 52000);\nclient = accept(srv);\nclientId = client.__tcpclient_id;\nfprintf(\"Opaque client identifier: %d\\\\n\", clientId)",
"output": "Opaque client identifier: 42 % identifier value varies per run"
}
],
"faqs": [
{
"question": "What happens if the server struct is invalid or already closed?",
"answer": "RunMat reports `RunMat:accept:InvalidTcpServer`. Ensure you pass the struct returned by `tcpserver` and that the server is still active."
},
{
"question": "Can I accept multiple clients with the same server?",
"answer": "Yes. Call `accept` repeatedly; each successful call registers a new client and returns its own struct while keeping the listener active."
},
{
"question": "How do I change the timeout globally?",
"answer": "Configure it when creating the server (`tcpserver(..., \"Timeout\", seconds)`). You can override it per call with `accept(srv, \"Timeout\", value)` if needed."
},
{
"question": "Does RunMat support IPv6 clients?",
"answer": "Yes. The builtin accepts IPv4 or IPv6 clients and records their string representation in the returned struct’s `Address` field."
},
{
"question": "Is there a queue limit for pending connections?",
"answer": "The OS backlog applies. If the queue is full, new clients may be refused before `accept` sees them. Increase the backlog with OS-level tuning if needed."
},
{
"question": "Can I use `accept` in parallel workers?",
"answer": "Yes. The listener must exist in the worker where you call `accept`, just like MATLAB. Future high-level helpers will coordinate cross-worker sharing."
},
{
"question": "How do I close the accepted client?",
"answer": "Use forthcoming networking close helpers (or invoke platform APIs directly). Dropping the struct does not close the socket automatically; RunMat networking builtins reference the opaque identifier."
},
{
"question": "What does `NumBytesAvailable` represent?",
"answer": "It mirrors MATLAB: the number of bytes buffered and ready to read. Initially zero; reading functions update it as data arrives."
},
{
"question": "Does the builtin support TLS?",
"answer": "Not yet. TLS will be layered on top of the same client identifier once RunMat’s TLS provider lands."
}
],
"links": [
{
"label": "tcpserver",
"url": "./tcpserver"
},
{
"label": "close",
"url": "./close"
},
{
"label": "read",
"url": "./read"
},
{
"label": "readline",
"url": "./readline"
},
{
"label": "tcpclient",
"url": "./tcpclient"
},
{
"label": "write",
"url": "./write"
}
],
"source": {
"label": "crates/runmat-runtime/src/builtins/io/net/accept.rs",
"url": "crates/runmat-runtime/src/builtins/io/net/accept.rs"
},
"gpu_residency": "No. TCP sockets run on the host, and `accept` gathers any GPU-resident scalars or structs before waiting for a connection. Keeping metadata on the GPU offers no benefit, and the builtin always returns CPU-resident structs with identifiers that reference host networking resources.",
"gpu_behavior": [
"`accept` does not involve the GPU. Any inputs that originate on the GPU are gathered before validation to make sure socket operations run on the host. The returned struct is always CPU-resident. No acceleration-provider hooks are required for this builtin, and future GPU-aware networking features will continue to gather metadata automatically while keeping sockets on the host."
]
}