Lynxer

Documentation

Original Lynxer surface: status

The original interpreter exposed a larger built-in and module surface than the standalone C++ runtime. This page catalogues it so programs and notes written against the original have somewhere to look, and records what has since been brought across. limitations documents current runtime and standard-library constraints.

Three statuses are used:

Pointers and raw addresses

The original had C-style address and function-pointer built-ins.

NameStatusNotes
getAddress(value)ImplementedValidates an integer as a live native allocation
getAddressValue(address)ImplementedReads an int64 from the address
modifyAddressValue(address, value)ImplementedWrites an int64 to the address
functionAddress / nativeFunctionAddressImplementedTyped non-zero function address (functionAddress is a declared type)
nativeCall(address, signature, arguments)ImplementedCalls a function pointer through the small integer ABI
nativeHandleAllocate/Address/Free/IsAliveImplementedOwned native handles (see below)

Addresses are plain integers, as the original documented, and the raw forms are implemented. nativeCall restricts signatures to the shapes the runtime supports and cannot make an arbitrary ABI safe — an invalid address can still crash the process. Prefer the structured built-ins when they fit — typed blocks (memoryBlockAllocate/memoryBlockGet/memoryBlockSet), native structs (nativeStructAllocate/nativeStructGet/nativeStructSet over a layout string), and owned handles (nativeHandleAllocate/nativeHandleAddress/ nativeHandleFree); see builtins.

Advanced memory layout

The original could model typed blocks and C structs directly in the allocator. All of it is implemented, including page protection and atomic/volatile access.

FamilyStatusNotes
memoryBlockAllocate/View/Get/Set/LengthImplementedTyped blocks: an element type and count
memoryArrayAllocate/View/Get/Set/Length, memoryViewGet/Set/LengthImplementedAliases of the block API
memoryStructSize/FieldOffset/FieldSize/Alignment/FieldCount/FieldType/Allocate/Get/SetImplementedLayout-string struct helpers
nativeStruct*, nativeTypeAlignmentImplementedAliases of the memoryStruct* / memoryTypeAlignment names
memoryProtectImplementedChange page protection (POSIX, page-granular)

A layout is a comma-separated type name list, e.g. "int32 id, float64 score"; see builtins.

Native synchronization

FamilyStatusNotes
nativeMutexCreate/Lock/TryLock/Unlock/CloseImplementedNon-recursive; only the owning thread may unlock
nativeConditionCreate/Wait/Notify/NotifyAll/CloseImplementedThe caller must hold the mutex for every operation
nativeSemaphoreCreate/Wait/TryWait/Post/CloseImplementedClosing is refused while a thread waits

Caveat: Lynxer evaluates on one interpreter thread under a single lock, and these handles sit on top of the cooperative nativeThread* model. A blocking wait releases the interpreter lock so another thread can run, but a wait on a resource no other thread will release deadlocks. See builtins.

Async

The async* family is implemented: asyncRun, asyncGather, asyncSleep, the asyncPoll* set, and the timer/wakeup built-ins. The async language syntax also exists — a local async name(params){...} definition called as async.name(args) — but it is eager, not a coroutine. asyncRun starts thread-backed tasks; await joins a task handle, and asyncGather joins the handles it receives. Tasks interleave at blocking or yield points, while the global interpreter lock prevents simultaneous Lynxer evaluation. See async and builtins.

Python bridging

NameStatusNotes
rawPy, rawPyx, cleanRawPyxCache, embedPyNot plannedEmbedded CPython/Cython

Why: Lynxer does not ship or link a Python runtime. Anything that depended on rawPy { } — including the original tkinter modules and tuple interop — has no direct equivalent. turtle is separately implemented over graphics.

FFI and native-module handles

FamilyStatusNotes
nativeModuleLoad/Name/Function/Constant/Type/Error/Dependencies/CloseImplementedDynamic discovery over the same ABI as importAs
ffiLoadLibrary, ffiLookup, ffiCloseLibrary, ffiCall, ffiCallback, ffiFreeCallbackImplementedC++ front end (lynxer/builtins.cpp) over the Rust libffi engine (lynxer/rust/ffi)

Native code is reached through the documented native-module ABI: an .so exporting lynxer_module_init_v1 is imported by name (importAs("libx.so", "x")), or loaded explicitly with nativeModuleLoad and inspected by name. Both share the same loader and registration rules; the ffi* family is the plain-symbol alternative. See builtins.

Modules not ported

ModuleStatusReplacement
venvNot plannedNone — a virtual environment is a CPython concept
tkinter, tkinterPlusDeclinedNo second GUI stack beside graphics (L16 in todo.md)
turtleImplementedturtle, drawn through graphics
http, netSupersedednetwork + server
mathPlusMergedmath (the float sign is signFloat)

Toolchain surface removed

FeatureStatusReplacement
Bytecode (.lynxc, --view-bytecode, --benchmark-compile, --no-cache)Removed--compile produces a standalone ELF executable
Python migration/ guideRemovedThe language reference in language
Python-only build paths (clynxer/, PyInstaller targets)Removedmake buildLynxer and the root Makefile

Quick map: original → now

OriginalNow
getAddress / getAddressValue / modifyAddressValueImplemented (addresses are integers)
nativeFunctionAddress / nativeCallImplemented (nativeCall over the small integer ABI)
nativeHandle*Implemented under the same names
nativeMutex* / Condition* / Semaphore*Implemented (cooperative handles)
async*Implemented (thread-backed tasks, serialized evaluation under the GIL)
rawPy / embedPyNone (no CPython)
nativeModule* handlesImplemented (importAs("<name>.so", …) is the usual route)
tkinter / tkinterPlusDeclined (no second GUI toolkit)
turtleImplemented over graphics
venvNone (CPython-only feature)

See also