> Web 4 < A Revolution in Programming
The link between Java and C. Two channels, one shared block of RAM, and commands flowing both ways.
Each side is named for the side it talks to. The Java side is CChannel, because from Java it is the channel to C. The C side is JavaChannel, because from C it is the channel to Java.
Both sides share the same RAM: the JavaShm shared-memory segment inside JavaChannel. No copying across a socket. Java and C read and write the same bytes.
Java (CChannel) <==> [ JavaShm shared RAM ] <==> C (JavaChannel)
Segment JavaChannel_SBI: 64 B header + 16 slots x 512 B = 8256 B. Everything is big-endian, on the wire and in memory (layout version 2; little-endian v1 is refused).
| Offset | Size | Field | Description |
|---|---|---|---|
| 0x0000 | 0x04 | magic | 0x4853434A ("HSCJ") |
| 0x0004 | 0x04 | version | 2 |
| 0x0008 | 0x04 | slot_count | 16 |
| 0x000C | 0x04 | slot_size | 512 |
| 0x0010 | 0x04 | header_size | 64 |
| 0x0014 | 0x04 | payload_off | Slot-relative offset of the up payload (128) |
| 0x0018 | 0x04 | owner_pid | PID of the JavaChannel owner |
| 0x001C | 0x04 | endian | 0x01020304; a reader that sees 04 03 02 01 refuses |
| 0x0020 | 0x08 | owner_hb_ms | Owner heartbeat (ms since epoch), written every 500 ms |
| 0x0028 | 0x04 | stale_sec | 3: a slot whose heartbeat is older than 3 s is reclaimed |
| 0x002C | 0x04 | payload_cap | 192 |
| 0x0030 | 0x10 | reserved | 0 |
| Offset | Size | Field | Description |
|---|---|---|---|
| 0x000 | 0x08 | state | 0 = free; else heartbeat seconds (high 32) | client PID (low 32). Claimed by CAS 0 -> state |
| 0x008 | 0x08 | hb_ms | Client heartbeat (ms) |
| 0x010 | 0x04 | seq_up | Seqlock, Java -> C payload |
| 0x014 | 0x04 | len_up | Bytes valid in up payload (0..192) |
| 0x018 | 0x04 | seq_dn | Seqlock, C -> Java payload |
| 0x01C | 0x04 | len_dn | Bytes valid in down payload |
| 0x020 | 0x60 | cdrec | ChannelData record (reserved) |
| 0x080 | 0xC0 | up | Java -> C payload (192 B) |
| 0x140 | 0xC0 | dn | C -> Java payload (192 B) |
A command is u16 op | u16 arglen | args, big-endian. Opcode = direction | verb; C to Java is 0x0100. Every command except NOP/ACK/NACK is answered with an ACK carrying its rc.
| Opcode | Command | What it does today | Return code |
|---|---|---|---|
| 0x0102 | OPEN_HYPERWINDOW | Binds the window id to the JVM's HyperView | rc=0, or 1 when it binds the running view |
| 0x0103 | GOB_CREATE | Creates a graphics object (#RRGGBB = solid fill, else image) | rc=0, -6 on failure |
| 0x0104 | GOB_MOVE | Moves a graphics object | rc=0, or -5 when not found |
| 0x0105 | GOB_SHOW | Shows (1) or hides (0) a graphics object | rc=0, or -5 when not found |
| 0x0106 | GOB_EXPUNGE | Removes a graphics object | rc=0, or -5 when not found |
| 0x0116 | WIN_MOVE | Moves the Java frame | rc=0 |
| 0x0117 | WIN_SIZE | Resizes the Java frame | rc=0 |
| 0x0118 | WIN_DRAW | Shows a w x h BGRA rect from a BUFFER_MAP buffer | rc=0, -5 buffer not mapped, -1 buffer too small |
| 0x0119 | WIN_EVENTS | Sets the event mask (1 input, 2 resize, 4 frame sync, 8 close) | rc=0 |
WIN_DRAW release: C keeps one entry per WIN_DRAW: seq -> (window, buffer). The ACK carries that seq and releases exactly that entry and its buffer, never every buffer on the window. ACKs may arrive in any order.
Java to C opcodes are 0x0200 | verb. Java ACKs every command it receives.
| Opcode | Message | What it does | Status |
|---|---|---|---|
| 0x0001 | ACK | Acknowledges a command: op, rc, id, and the seq of the payload it answers | in use |
| 0x0014 | NACK | Refuses a command with rc < 0 (same layout as ACK) | in use |
| 0x0210 | INPUT_EVENT | Keyboard/mouse input as an EventNexus code; other codes get E_BADOP | in use |
| 0x0211 | RESIZE_EVENT | Window changed size (EventNexus WINDOW_RESIZED) | in use |
| 0x0212 | FRAME_SYNC | Frame finished (win, frame no, ms). Command-only: no EventNexus row | in use |
Verbs 0-28 are final. Verbs 29 and above are unknown and return E_BADOP (-2).
| Verb | Command | Direction | What it does today |
|---|---|---|---|
| 0 | NOP | any | Padding, ignored |
| 1 | ACK | any | Answers a command; releases flow control and the matching WIN_DRAW |
| 2-6 | OPEN_HYPERWINDOW, GOB_* | both | Java: window bind and graphics objects. C: served on container-owned slots, else E_UNBOUND |
| 7 | SAY | both | Text line; C replies with the next line |
| 8 | HELLO | both | Handshake, protocol 0x0201; E_VERSION if major is not 2 |
| 9 | CLOSE_HYPERWINDOW | both | Unbinds the window; the JVM's only view stays open |
| 10 | GOB_RESIZE | both | Java: E_UNBOUND, not yet implemented |
| 11 | GOB_SET_TEXTURE | both | Java: E_UNBOUND, not yet implemented |
| 12 | GOB_SET_SHADER | Java to C | Attaches a shader; E_NOGPU without a GPU context |
| 13 | SHADER_LOAD | Java to C | Loads a SPIR-V compute/vertex/fragment shader; E_NOGPU without GPU |
| 14 | GPU_DISPATCH | Java to C | Runs a compute shader; E_NOGPU without GPU |
| 15 | BUFFER_MAP | both | C creates (bytes > 0) or destroys (bytes 0) a buffer; Java opens existing only. The wire carries the bare name JavaChannel_SBI_buf<id>; each side adds its own platform prefix |
| 16 | INPUT_EVENT | both | Keyboard/mouse EventNexus rows only, else E_BADOP |
| 17 | RESIZE_EVENT | both | Recorded |
| 18 | FRAME_SYNC | both | Recorded; command-only, no EventNexus row |
| 19 | PING | both | ACK with the nonce |
| 20 | NACK | any | Refusal; releases the wait like ACK |
| 21 | SHUTDOWN | both | ACK, then a clean close of the link |
| 22-25 | WIN_MOVE, WIN_SIZE, WIN_DRAW, WIN_EVENTS | C to Java | Drive the Java frame from C (all four work) |
| 26 | OBJ_SYNC | both | Java echoes/increments a shared counter Object; C: bound handler, else E_UNBOUND |
| 27 | VIEWFRAME | both | Java opens a frame with Abort (E_BUSY if one is open); C: bound handler, else E_UNBOUND |
| 28 | VIEWFRAME_DONE | both | Reports the frame finished and was removed; C: bound handler, else E_UNBOUND |
| 29+ | (unknown) | - | E_BADOP on both sides |
JavaShm v2.1 · 2026-10-16