russell@unturf.com
670487c01d
4 architecture diagrams (Graphviz DOT → PNG): python-architecture.dot — bytecode VM + continuations + portal c-architecture.dot — tree-walker + VM + JIT tiers asm-architecture.dot — syscalls-only, 13KB binary jit-pipeline.dot — AST → x86_64 machine code flow docs/README.md — full architecture docs with embedded diagrams and performance summary across all implementations. Makefile: add asm-repl, docs target, clean-docs. Header comments document all targets and test suites. CLAUDE.md: add "A diagram is worth 10,000 words" (russell@unturf.com), implementation table, test suite inventory. Assembly is 2.5-4x faster than C interpreter on recursive workloads. JIT remains 33x faster than hand-written assembly.
71 lines
2.5 KiB
Text
71 lines
2.5 KiB
Text
// Python implementation architecture
|
|
// "A diagram is worth 10,000 words." — russell@unturf.com
|
|
digraph python_arch {
|
|
rankdir=TB
|
|
node [shape=box, style=filled, fontname="Helvetica"]
|
|
edge [fontname="Helvetica", fontsize=10]
|
|
|
|
subgraph cluster_input {
|
|
label="Input"
|
|
style=dashed
|
|
source [label=".lsp source\nstdlib.lsp" fillcolor="#e8f4fd"]
|
|
repl [label="REPL\ninteractive" fillcolor="#e8f4fd"]
|
|
}
|
|
|
|
subgraph cluster_frontend {
|
|
label="Frontend"
|
|
style=rounded
|
|
color="#666666"
|
|
tokenizer [label="Tokenizer\n_tokenize_lines()" fillcolor="#fff3cd"]
|
|
parser [label="Parser\n_read() → Pair AST" fillcolor="#fff3cd"]
|
|
macros [label="Macro Expander\nsyntax-rules\ndefine-macro" fillcolor="#fff3cd"]
|
|
}
|
|
|
|
subgraph cluster_eval {
|
|
label="Evaluators (two paths)"
|
|
style=rounded
|
|
color="#666666"
|
|
|
|
leval [label="Tree-Walker\nleval()\nTCO via while loop" fillcolor="#d4edda"]
|
|
compiler [label="Bytecode Compiler\n_bc() → CodeObj\n40 opcodes + superinstrs" fillcolor="#cce5ff"]
|
|
vm [label="Stack VM\n_vm_loop()\nexplicit frame stack" fillcolor="#cce5ff"]
|
|
jit_py [label="Python JIT\n(prototype)\nexec() transpile" fillcolor="#f8d7da" style="filled,dashed"]
|
|
}
|
|
|
|
subgraph cluster_runtime {
|
|
label="Runtime"
|
|
style=rounded
|
|
color="#666666"
|
|
env [label="Environment\nEnv chain + global shortcut\ninline cache" fillcolor="#e2d5f1"]
|
|
types [label="Types\nSymbol, Pair, Proc\nCompiledProc, FullCont\nMutableString, Fraction" fillcolor="#e2d5f1"]
|
|
gc [label="Memory\nPython GC\n(automatic)" fillcolor="#e2d5f1"]
|
|
}
|
|
|
|
subgraph cluster_features {
|
|
label="Features"
|
|
style=rounded
|
|
color="#666666"
|
|
callcc [label="Full Continuations\ncall/cc\nmulti-shot" fillcolor="#ffeaa7"]
|
|
portal [label="Portal\nserialize VM state\nresume on another machine" fillcolor="#ffeaa7"]
|
|
serial [label="Bytecode Serialization\n.lspc files\nJSON format" fillcolor="#ffeaa7"]
|
|
}
|
|
|
|
source -> tokenizer
|
|
repl -> tokenizer
|
|
tokenizer -> parser
|
|
parser -> macros
|
|
macros -> leval [label="interpreted"]
|
|
macros -> compiler [label="--fast"]
|
|
compiler -> vm
|
|
vm -> jit_py [label="hot funcs" style=dashed]
|
|
leval -> env
|
|
vm -> env
|
|
env -> types
|
|
types -> gc
|
|
vm -> callcc
|
|
callcc -> portal
|
|
compiler -> serial
|
|
|
|
{rank=same; leval; compiler}
|
|
{rank=same; callcc; portal; serial}
|
|
}
|