MultiverseSocial · /dev · javachannel

JavaChannel and CChannel

> Web 4 < A Revolution in Programming

The link between Java and C. Two channels, one shared block of RAM, and commands flowing both ways.

Java side: CChannel C side: JavaChannel shared RAM: JavaShm

What the link is

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)

What this gives you

1. JavaShm RAM layout (v2.1)

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).

Header (offset 0, 64 B)

OffsetSizeFieldDescription
0x00000x04magic0x4853434A ("HSCJ")
0x00040x04version2
0x00080x04slot_count16
0x000C0x04slot_size512
0x00100x04header_size64
0x00140x04payload_offSlot-relative offset of the up payload (128)
0x00180x04owner_pidPID of the JavaChannel owner
0x001C0x04endian0x01020304; a reader that sees 04 03 02 01 refuses
0x00200x08owner_hb_msOwner heartbeat (ms since epoch), written every 500 ms
0x00280x04stale_sec3: a slot whose heartbeat is older than 3 s is reclaimed
0x002C0x04payload_cap192
0x00300x10reserved0

Slot i (offset 0x40 + 0x200 x i)

OffsetSizeFieldDescription
0x0000x08state0 = free; else heartbeat seconds (high 32) | client PID (low 32). Claimed by CAS 0 -> state
0x0080x08hb_msClient heartbeat (ms)
0x0100x04seq_upSeqlock, Java -> C payload
0x0140x04len_upBytes valid in up payload (0..192)
0x0180x04seq_dnSeqlock, C -> Java payload
0x01C0x04len_dnBytes valid in down payload
0x0200x60cdrecChannelData record (reserved)
0x0800xC0upJava -> C payload (192 B)
0x1400xC0dnC -> Java payload (192 B)

Liveness and close

2. Commands, C to Java

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.

OpcodeCommandWhat it does todayReturn code
0x0102OPEN_HYPERWINDOWBinds the window id to the JVM's HyperViewrc=0, or 1 when it binds the running view
0x0103GOB_CREATECreates a graphics object (#RRGGBB = solid fill, else image)rc=0, -6 on failure
0x0104GOB_MOVEMoves a graphics objectrc=0, or -5 when not found
0x0105GOB_SHOWShows (1) or hides (0) a graphics objectrc=0, or -5 when not found
0x0106GOB_EXPUNGERemoves a graphics objectrc=0, or -5 when not found
0x0116WIN_MOVEMoves the Java framerc=0
0x0117WIN_SIZEResizes the Java framerc=0
0x0118WIN_DRAWShows a w x h BGRA rect from a BUFFER_MAP bufferrc=0, -5 buffer not mapped, -1 buffer too small
0x0119WIN_EVENTSSets 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.

3. Commands, Java to C

Java to C opcodes are 0x0200 | verb. Java ACKs every command it receives.

OpcodeMessageWhat it doesStatus
0x0001ACKAcknowledges a command: op, rc, id, and the seq of the payload it answersin use
0x0014NACKRefuses a command with rc < 0 (same layout as ACK)in use
0x0210INPUT_EVENTKeyboard/mouse input as an EventNexus code; other codes get E_BADOPin use
0x0211RESIZE_EVENTWindow changed size (EventNexus WINDOW_RESIZED)in use
0x0212FRAME_SYNCFrame finished (win, frame no, ms). Command-only: no EventNexus rowin use

4. Full verb set (final for v2.1)

Verbs 0-28 are final. Verbs 29 and above are unknown and return E_BADOP (-2).

VerbCommandDirectionWhat it does today
0NOPanyPadding, ignored
1ACKanyAnswers a command; releases flow control and the matching WIN_DRAW
2-6OPEN_HYPERWINDOW, GOB_*bothJava: window bind and graphics objects. C: served on container-owned slots, else E_UNBOUND
7SAYbothText line; C replies with the next line
8HELLObothHandshake, protocol 0x0201; E_VERSION if major is not 2
9CLOSE_HYPERWINDOWbothUnbinds the window; the JVM's only view stays open
10GOB_RESIZEbothJava: E_UNBOUND, not yet implemented
11GOB_SET_TEXTUREbothJava: E_UNBOUND, not yet implemented
12GOB_SET_SHADERJava to CAttaches a shader; E_NOGPU without a GPU context
13SHADER_LOADJava to CLoads a SPIR-V compute/vertex/fragment shader; E_NOGPU without GPU
14GPU_DISPATCHJava to CRuns a compute shader; E_NOGPU without GPU
15BUFFER_MAPbothC 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
16INPUT_EVENTbothKeyboard/mouse EventNexus rows only, else E_BADOP
17RESIZE_EVENTbothRecorded
18FRAME_SYNCbothRecorded; command-only, no EventNexus row
19PINGbothACK with the nonce
20NACKanyRefusal; releases the wait like ACK
21SHUTDOWNbothACK, then a clean close of the link
22-25WIN_MOVE, WIN_SIZE, WIN_DRAW, WIN_EVENTSC to JavaDrive the Java frame from C (all four work)
26OBJ_SYNCbothJava echoes/increments a shared counter Object; C: bound handler, else E_UNBOUND
27VIEWFRAMEbothJava opens a frame with Abort (E_BUSY if one is open); C: bound handler, else E_UNBOUND
28VIEWFRAME_DONEbothReports 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

Hits--