Skip to content

stdnet.md

Latest commit

 

History

History
75 lines (63 loc) · 3.46 KB

stdnet.md

File metadata and controls

75 lines (63 loc) · 3.46 KB
module STDNET
tag v0.8.0
phase M2 — VSL/MSL S4 socket seam
stable stable
since v0.8.0
synopsis portable raw-TCP socket primitives (engine-native sockets)
labels
accept
available
boundport
close
connect
listen
read
write
errors
conformance
see_also
STDHTTP

STDNET — portable raw-TCP socket primitives

STDNET is the portable socket seam (S4 of the MSL⟷VSL coordination plan): a thin, handle-based, raw-byte TCP API that any pure-M service can use on a bare engine, and that the VistA VSLIO adapter binds to VistA's device handler (^%ZIS / CALL^%ZISTCP) above the m/v waterline. It drives each engine's native socket device — no C call-outs — with the (large) engine divergence isolated behind $ZVERSION["IRIS" arms.

@tier optional — engine-sensitive and, today, YottaDB-only.

Public API

All transfers are raw bytes: no record delimiter, no packet framing. Handles are small integers; per-handle state (device name, accepted-socket name, bound port) lives in the process-private ^STDLIB($job,"stdnet",id,*).

Call Purpose
$$available^STDNET() 1 iff raw sockets are wired on this engine
$$listen^STDNET(port) open a listening socket (0 ⇒ OS-assigned port) → handle, or 0
$$boundport^STDNET(id) the actual bound port of a listener handle
$$accept^STDNET(id,timeout) accept a pending connection → connection handle, or 0
$$connect^STDNET(host,port,timeout) client connect → handle, or 0
$$read^STDNET(id,maxlen,timeout,.buf) raw-read up to maxlen bytes → count, buf by-ref
$$write^STDNET(id,buf) raw-write buf → 1/0
$$close^STDNET(id) close a handle (idempotent) → 1

Loopback echo (the shape STDNETTST proves)

set srv=$$listen^STDNET(0)                     ; OS-assigned port
set port=$$boundport^STDNET(srv)
set cli=$$connect^STDNET("127.0.0.1",port,5)
set conn=$$accept^STDNET(srv,5)                ; the server-side connection
if $$write^STDNET(cli,"ping")
set n=$$read^STDNET(conn,99,5,.buf)            ; buf="ping"
if $$write^STDNET(conn,buf)                    ; echo back
set n=$$read^STDNET(cli,99,5,.buf)             ; buf="ping"
set n=$$close^STDNET(cli),n=$$close^STDNET(conn),n=$$close^STDNET(srv)

Engine support & portability

  • YottaDB — implemented. YottaDB's SOCKET device is a collection of sockets per device, so a single process can listen + connect + accept (the loopback the suite uses). accept is WRITE /WAIT, which auto-accepts the connection — the new socket handle is $PIECE($KEY,"|",2) (there is no separate /ACCEPT; that raises LOCALSOCKREQ). Each verb saves/restores $IO so it never disturbs the caller's current device.
  • IRIS — not yet wired: $$available^STDNET() returns 0, every verb returns its safe-failure value, and STDNETTST soft-skips green (the same posture as STDHTTP's libcurl soft-fail). The IRIS leg (the |TCP| device + a JOB'd connector for loopback, since IRIS has no collection-of-sockets device) is the owed follow-up, to be live-verified on m-test-iris.

Seam contract

The side-effecting verbs (listen/accept/connect/read/write/close) carry ; doc: @seam STDNET → the seams.STDNET block of dist/stdlib-manifest.json (+ dist/seam-snapshot.json). VSLIO (v-stdlib, M2) pins this contract and implements the same signatures over ^%ZIS/CALL^%ZISTCP + named TLS.