From f0a6c6757a795b8e186de0076836a87acef59fa7 Mon Sep 17 00:00:00 2001 From: Cliff Click Date: Sun, 15 Nov 2026 11:20:40 -0800 Subject: Graphics now allow resize Reorganize docs. Fix bugs X86 LOad+cmp scheduling. Math intrinsics --- README.md | 4 +- chapter27/README.md | 9 +- chapter28a/README.md | 5 + chapter28b/README.md | 4 +- chapter29/README.md | 51 ++- chapter29/docs/construction-groups.md | 6 +- chapter29/docs/deferred-construction.md | 5 + chapter29/docs/escape-flow.md | 6 +- chapter30/README.md | 8 +- chapter30/docs/30-grammar.ja.md | 2 +- chapter30/docs/30-grammar.md | 2 +- chapter30/docs/construction-groups.md | 241 ------------- chapter30/docs/deferred-construction.md | 385 --------------------- chapter30/docs/escape-flow.md | 147 -------- .../com/seaofnodes/simple/parser/Construction.java | 3 +- chapter31/README.ja.md | 9 +- chapter31/README.md | 150 ++++++-- chapter31/docs/31-grammar.ja.md | 6 +- chapter31/docs/31-grammar.md | 6 +- chapter31/docs/audio.md | 62 ---- chapter31/docs/construction-groups.md | 241 ------------- chapter31/docs/deferred-construction.md | 385 --------------------- chapter31/docs/drawing.md | 103 ------ chapter31/docs/escape-flow.md | 147 -------- chapter31/docs/examples/Breakout.smp | 21 +- chapter31/docs/examples/Clock.smp | 68 ++-- chapter31/docs/examples/Graphics.smp | 19 +- chapter31/docs/examples/README.md | 35 +- chapter31/docs/examples/TicTacToeGraphical.smp | 15 +- chapter31/docs/graphics.md | 132 ------- chapter31/docs/intrinsics.md | 53 --- chapter31/docs/time.md | 129 ------- chapter31/src/main/c/simple_crt.c | 10 + chapter31/src/main/c/simple_graphics.c | 8 +- chapter31/src/main/c/simple_graphics.h | 5 +- chapter31/src/main/c/simple_minifb.c | 39 ++- .../simple/codegen/GlobalCodeMotion.java | 10 +- .../seaofnodes/simple/codegen/ListScheduler.java | 2 +- .../com/seaofnodes/simple/codegen/RegAlloc.java | 12 +- .../java/com/seaofnodes/simple/node/ModFNode.java | 49 +++ .../java/com/seaofnodes/simple/node/ModNode.java | 16 + .../main/java/com/seaofnodes/simple/node/Node.java | 3 +- .../seaofnodes/simple/node/cpus/arm/ModARM.java | 29 ++ .../com/seaofnodes/simple/node/cpus/arm/arm.java | 3 +- .../seaofnodes/simple/node/cpus/riscv/DivRISC.java | 17 +- .../seaofnodes/simple/node/cpus/riscv/riscv.java | 1 + .../simple/node/cpus/x86_64_v2/CmpX86.java | 7 + .../simple/node/cpus/x86_64_v2/DivX86.java | 36 +- .../simple/node/cpus/x86_64_v2/x86_64_v2.java | 28 +- .../com/seaofnodes/simple/parser/Construction.java | 3 +- .../com/seaofnodes/simple/parser/Expressions.java | 4 +- .../java/com/seaofnodes/simple/parser/Lexer.java | 4 +- chapter31/src/main/smp/sys.smp | 2 +- chapter31/src/main/smp/sys/audio.md | 84 +++++ chapter31/src/main/smp/sys/audio.smp | 1 + chapter31/src/main/smp/sys/draw.smp | 1 + chapter31/src/main/smp/sys/draw/Canvas.smp | 68 +++- chapter31/src/main/smp/sys/draw/README.md | 124 +++++++ chapter31/src/main/smp/sys/gfx.md | 154 +++++++++ chapter31/src/main/smp/sys/gfx.smp | 19 +- chapter31/src/main/smp/sys/math.smp | 12 + chapter31/src/main/smp/sys/text.smp | 2 +- chapter31/src/main/smp/sys/time.smp | 26 +- chapter31/src/main/smp/sys/time/README.md | 133 +++++++ .../java/com/seaofnodes/simple/ArithNodeTest.java | 1 + .../java/com/seaofnodes/simple/BreakoutTest.java | 2 +- .../test/java/com/seaofnodes/simple/DrawTest.java | 61 ++-- .../src/test/java/com/seaofnodes/simple/Eval2.java | 3 + .../java/com/seaofnodes/simple/GraphicsTest.java | 58 +++- .../test/java/com/seaofnodes/simple/MathTest.java | 79 +++++ .../test/java/com/seaofnodes/simple/ModTest.java | 201 +++++++++++ .../java/com/seaofnodes/simple/SchedulingTest.java | 47 +++ .../java/com/seaofnodes/simple/StreamIOTest.java | 2 +- .../com/seaofnodes/simple/StringFormatTest.java | 5 + .../src/test/java/com/seaofnodes/simple/TestC.java | 2 +- docs/intellij.md | 2 +- skills/chapter-split.md | 6 +- skills/chapter25-codex-notes.md | 208 +++++------ 78 files changed, 1705 insertions(+), 2343 deletions(-) delete mode 100644 chapter30/docs/construction-groups.md delete mode 100644 chapter30/docs/deferred-construction.md delete mode 100644 chapter30/docs/escape-flow.md delete mode 100644 chapter31/docs/audio.md delete mode 100644 chapter31/docs/construction-groups.md delete mode 100644 chapter31/docs/deferred-construction.md delete mode 100644 chapter31/docs/drawing.md delete mode 100644 chapter31/docs/escape-flow.md delete mode 100644 chapter31/docs/graphics.md delete mode 100644 chapter31/docs/intrinsics.md delete mode 100644 chapter31/docs/time.md create mode 100644 chapter31/src/main/java/com/seaofnodes/simple/node/ModFNode.java create mode 100644 chapter31/src/main/java/com/seaofnodes/simple/node/ModNode.java create mode 100644 chapter31/src/main/java/com/seaofnodes/simple/node/cpus/arm/ModARM.java create mode 100644 chapter31/src/main/smp/sys/audio.md create mode 100644 chapter31/src/main/smp/sys/draw/README.md create mode 100644 chapter31/src/main/smp/sys/gfx.md create mode 100644 chapter31/src/main/smp/sys/time/README.md create mode 100644 chapter31/src/test/java/com/seaofnodes/simple/MathTest.java create mode 100644 chapter31/src/test/java/com/seaofnodes/simple/ModTest.java create mode 100644 chapter31/src/test/java/com/seaofnodes/simple/SchedulingTest.java diff --git a/README.md b/README.md index bc6feebe..ed70fb48 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ the backend starts with a Java evaluator (first introduced in Chapter Download dependencies once with `make libs` (or `make init`; `make lib` remains an alias). Other Make targets use the local `lib/` caches and never download. -For Chapter 31's graphics and audio, use `make -C chapter31 libs CTAGS=` while +For Chapter 31's graphics and audio, use `make -C chapter31 libs` while online; those cached sources survive `make clean` for later offline builds. The following is a rough plan, subject to change. @@ -117,7 +117,7 @@ Makefile additions introduce allocation statistics (20), shared instruction encoders (21), the native entry shim (28a), separate compilation and `sys` (28b), the terminal game (30), and graphics/audio (31). -CI runs `make lib tests CTAGS=` on Linux with JDK 21. The Make targets also build +CI runs `make lib tests` on Linux with JDK 21. The Make targets also build the native runtime and `sys` library in Chapter 28b and later before running the tests that use them; Maven's Java build alone does not produce those prerequisites. diff --git a/chapter27/README.md b/chapter27/README.md index 758a7745..3e6a3810 100644 --- a/chapter27/README.md +++ b/chapter27/README.md @@ -165,12 +165,17 @@ read of an uninitialized field is legal. These are separate checks. The runnable construction and escape snapshots now make that border available for review. Neither topic requires the other to be taught first. +The [module chapter](../chapter28a/README.md#escaping-or-the-startstop-cycle) +extends this cycle to foreign identities and class initialization. +[Chapter 29](../chapter29/README.md#keeping-private-code-out-of-the-outside-world-summary) +explains the later precision fixes and links the detailed implementation notes. + ## Build and check -From this directory, run `make lib tests CTAGS=`. From the repository root, run: +From this directory, run `make lib tests`. From the repository root, run: ```bash -make tests CHAPTERS=chapter27 CTAGS= +make tests CHAPTERS=chapter27 ``` `EscapeTest` checks the recursive callback, direct and indirect returned diff --git a/chapter28a/README.md b/chapter28a/README.md index 3dec4c4f..2f127e19 100644 --- a/chapter28a/README.md +++ b/chapter28a/README.md @@ -259,6 +259,11 @@ initializer's memory effects, and unknown callbacks participate in class-init cycle detection through the functions that have escaped. +The [detailed escape-flow notes](../chapter29/docs/escape-flow.md) describe the +consumer dependencies and foreign-identity exclusions. The design was developed +in Chapter 29 and backported here using this chapter's `LocalIds` and existing +initializer protocol; its later construction changes are not part of this snapshot. + ## Emitting code and data After cleanup by `FinishCalls`, the live code and data from the discovered diff --git a/chapter28b/README.md b/chapter28b/README.md index d581d868..84e538ea 100644 --- a/chapter28b/README.md +++ b/chapter28b/README.md @@ -120,7 +120,9 @@ those exclusions by owner and slot, then restores the complement. Treating this set as FULL would expose private library functions. Unknown callback arguments, results, and unloaded summaries use the evolving Start/Stop state; no frozen public-function list supplies their bounds. Hidden class receivers -default to the defining class singleton even after import. +default to the defining class singleton even after import. The +[escape-flow implementation notes](../chapter29/docs/escape-flow.md) explain +the shared design and the identity-remapping checks in more detail. `ParseAll` is the workhorse that discovers source and object dependencies. It tracks missing symbol references, looking them up in the search path one by one, diff --git a/chapter29/README.md b/chapter29/README.md index db6e90fd..ed39de98 100644 --- a/chapter29/README.md +++ b/chapter29/README.md @@ -136,12 +136,61 @@ and the [construction notes](docs/construction-groups.md) explain the type flow, memory edges, and remaining restrictions. +## Keeping private code out of the outside-world summary + +[Chapter 27](../chapter27/README.md#start-and-stop-close-the-cycle) explains how +Start and Stop discover which objects and functions unknown code can reach. +The module and separate-compilation snapshots extend that cycle to foreign +identities. This chapter's construction cleanup also exposed places where an +unnecessarily broad value could undo that precision. + +Suppose a library passes a callback to native code. The callback has escaped: +native code may call it or return its address later. Another private callback +that the library never exposes must stay private. Treating every unknown +callback result as every possible function would lose that distinction. + +The outside state therefore starts with foreign identities and gains local +identities only as they escape. A finite set of exclusions represents the +locally owned identities that the outside world cannot yet reach. Start feeds +this state into unknown callers and native results; Stop discovers newly exposed +addresses. Ordinary SCCP repeats the cycle until it stabilizes. Public +declarations help select entry points; a frozen list of public names cannot +replace the evolving escape state. + +Consumers must track changes to this state even when control does not change. +For example, CallEnd depends directly on Start because a call can remain live +while additional callbacks escape. Local pointer facts matter too: preserving +non-nullness through conversions and recovering stored pointer types during +Load computation prevents an avoidable unknown value from widening the whole +cycle. Class-init effects come from the known initializer's Return, and a class +function's implicit receiver defaults to its owning singleton. + +The [outside-world escape-flow notes](docs/escape-flow.md) cover the detailed +dependencies, imported identities, and regression examples. That design was +developed here and backported to Chapters 28a/28b; the Chapter 27 snapshot retains +the earlier analysis taught in its README. + +## Implementation notes and experiments + +The explanations above describe the chapter's implemented behavior. For a +closer look at particular mechanisms: + +- [Construction field types and incomplete references](docs/construction-groups.md) + covers field views, aliases, loops, and the separate deferred contract proposal. +- [Deferring construction checks](docs/deferred-construction.md) records the + experiment that removed the extra construction pass. Its historical failures + and abandoned escape fallback are superseded by the escape-flow continuation. +- [Outside-world escape flow](docs/escape-flow.md) records the final design and + the differences between its 28a, 28b, and 29 implementations. + +Later chapters inherit the implementation and link here for these topics. + ## Build and test From the repository root: ```sh -make lib tests release CHAPTERS=chapter29 CTAGS= +make lib tests release CHAPTERS=chapter29 ``` The suite includes the inherited compiler, evaluator, native execution, diff --git a/chapter29/docs/construction-groups.md b/chapter29/docs/construction-groups.md index 197a6082..58ca526c 100644 --- a/chapter29/docs/construction-groups.md +++ b/chapter29/docs/construction-groups.md @@ -1,5 +1,8 @@ # Construction: field types and incomplete references +Start with [Chapter 29's constructor and partial-reference explanation](../README.md#checking-constructor-completion). +This supplement details the type flow and records a separate deferred proposal. + Instance constructors use ordinary field Loads and Stores. There are two checks: whether a field has a value, and whether an object reference is usable outside construction. Neither requires a collection of constructor-group identities. @@ -31,7 +34,8 @@ reads may be removed by DCE. The allocator's ConstructNode retains the constructor's final private memory for its completion check. TypeCheck gathers these nodes during its existing error walk and removes checked boundaries before lowering. The pass removal -exposes known failures; see [the late-check notes](deferred-construction.md). +exposed failures during development; the [late-check experiment](deferred-construction.md) +records them and links the subsequent escape-flow fixes. Internal construction memory parameters use actual allocation/initializer call edges; the hypothetical external caller does not supply their memory. They diff --git a/chapter29/docs/deferred-construction.md b/chapter29/docs/deferred-construction.md index 104ab9e9..e232e1c0 100644 --- a/chapter29/docs/deferred-construction.md +++ b/chapter29/docs/deferred-construction.md @@ -1,5 +1,10 @@ # Deferring construction checks: experiment +This is a development record for Chapter 29. Read the +[chapter's constructor explanation](../README.md#checking-constructor-completion) +for the implemented behavior; the experiments below include superseded approaches +and dated test results. + The [escape-flow continuation](escape-flow.md) supersedes the frozen-public fallback and remaining recursive-test failures described later in these notes. All four recursive examples now pass their original printed-IR expectations. diff --git a/chapter29/docs/escape-flow.md b/chapter29/docs/escape-flow.md index 8ad49f15..c09177ed 100644 --- a/chapter29/docs/escape-flow.md +++ b/chapter29/docs/escape-flow.md @@ -1,5 +1,9 @@ # Outside-world escape flow +For the teaching sequence, read [escape analysis in Chapter 27](../../chapter27/README.md) +and [the later precision fixes in Chapter 29](../README.md#keeping-private-code-out-of-the-outside-world-summary). +This supplement records implementation dependencies and backport details. + The `escape-flow` branch developed this design in Chapter29 and backported it to Chapters 28a/28b. Chapter28a uses `LocalIds` and its existing initializer root/lowering protocol; Chapter28b adds saved summaries and cofinite identity @@ -125,7 +129,7 @@ later. This limitation is not repaired by resetting the whole IR. ## Validation -The combined `make -k tests CHAPTERS="chapter28a chapter28b chapter29" CTAGS=` +The combined `make -k tests CHAPTERS="chapter28a chapter28b chapter29"` run passes with assertions: 538 active tests in Chapter28a, 578 in Chapter28b, and 601 in Chapter29. Shared printer and ISA checks pass too. The log is saved under ignored `build/escape-backport-final.log`. diff --git a/chapter30/README.md b/chapter30/README.md index 9ac38576..2e172e33 100644 --- a/chapter30/README.md +++ b/chapter30/README.md @@ -205,7 +205,7 @@ also deferred; the `int` change does not shrink pointers. The [grammar and code map](docs/30-grammar.md), [source layout](src/main/java/com/seaofnodes/simple/README.md), and -[construction notes](docs/construction-groups.md) describe the starting point. +[construction explanation in Chapter 29](../chapter29/README.md#checking-constructor-completion) describe the starting point. Open projects are listed in the [roadmap](../docs/roadmap.md). ## Build and test @@ -213,13 +213,13 @@ Open projects are listed in the [roadmap](../docs/roadmap.md). From the repository root: ```sh -make lib tests release CHAPTERS=chapter30 CTAGS= +make lib tests release CHAPTERS=chapter30 ``` Build the game without starting it: ```sh -make -C chapter30 tictactoe CTAGS= +make -C chapter30 tictactoe ``` The Windows/Cygwin build produces @@ -229,7 +229,7 @@ from Cygwin or PowerShell. Linux produces When building in WSL alongside Windows, keep Java build outputs separate: ```sh -make -C chapter30 tictactoe CLZDIR=build/classes-linux CTAGS= +make -C chapter30 tictactoe CLZDIR=build/classes-linux ``` IntelliJ has a `chapter30` module and a **chapter30 tests** run configuration. diff --git a/chapter30/docs/30-grammar.ja.md b/chapter30/docs/30-grammar.ja.md index 13fd500d..89e4793e 100644 --- a/chapter30/docs/30-grammar.ja.md +++ b/chapter30/docs/30-grammar.ja.md @@ -47,7 +47,7 @@ constructorParameterList : (constructorParameter ','?)+ ; constructorParameter : type '^'? bindingModifier? IDENTIFIER ; // ^ accepts an unfinished struct reference; ? independently permits null. // Only self may be read while incomplete; ^ arguments may be stored/forwarded. -// A new result is incomplete iff an actual argument is. See construction-groups.md. +// A new result is incomplete iff an actual argument is. See ../../chapter29/README.md#incomplete-types. // A method is an ordinary fixed function binding in a struct definition. // The compiler supplies self; it is not written in parameterList. diff --git a/chapter30/docs/30-grammar.md b/chapter30/docs/30-grammar.md index 3bddfb87..189a7c04 100644 --- a/chapter30/docs/30-grammar.md +++ b/chapter30/docs/30-grammar.md @@ -56,7 +56,7 @@ constructorParameterList : (constructorParameter ','?)+ ; constructorParameter : type '^'? bindingModifier? IDENTIFIER ; // ^ accepts an unfinished struct reference; ? independently permits null. // Only self may be read while incomplete; ^ arguments may be stored/forwarded. -// A new result is incomplete iff an actual argument is. See construction-groups.md. +// A new result is incomplete iff an actual argument is. See ../../chapter29/README.md#incomplete-types. // A method is an ordinary fixed function binding in a struct definition. // The compiler supplies self; it is not written in parameterList. diff --git a/chapter30/docs/construction-groups.md b/chapter30/docs/construction-groups.md deleted file mode 100644 index 197a6082..00000000 --- a/chapter30/docs/construction-groups.md +++ /dev/null @@ -1,241 +0,0 @@ -# Construction: field types and incomplete references - -Instance constructors use ordinary field Loads and Stores. There are two checks: -whether a field has a value, and whether an object reference is usable outside -construction. Neither requires a collection of constructor-group identities. - -## Field initialization - -New produces private `TypeMem` containing the object's `TypeStruct`, with -`TypeScalar.BOT` for fresh fields. Defaults emit ordinary Stores: zero for an -ordinary integer, null for a nullable pointer, no Store for a required field. -An assignment strongly updates its field in private memory. Phi meets the -incoming memories; a missing live arm survives because `BOT.meet(7) == BOT`. -An initialized unknown integer has `TypeInteger.BOT`, not `TypeScalar.BOT`. -Arrays retain their language-level zero filling. - -One `#selfMem` binding carries this memory through scopes and returns. A Load -checks its incoming field type. Constructor completion checks the merged Return -memory; the explicit constructor receives the declaration initializer's merged -result, including early exits. There is no backwards initialization query, -per-field parser state, or store-all instance exit. - -The existing Iter/Opto passes propagate these types; TypeCheck reports errors. -There is no extra construction type solve or retained source-use list. An -initialized field carried unchanged around a loop needs the optimistic SCCP -solution. Numeric fields in loop memory widen as scalar loop values do. -Arithmetic, conversions, and numeric Stores preserve Scalar.BOT, so a live bad -read cannot disappear merely because it is multiplied by zero. Genuinely unused -reads may be removed by DCE. - -The allocator's ConstructNode retains the constructor's final private memory -for its completion check. TypeCheck gathers these nodes during its existing -error walk and removes checked boundaries before lowering. The pass removal -exposes known failures; see [the late-check notes](deferred-construction.md). - -Internal construction memory parameters use actual allocation/initializer call -edges; the hypothetical external caller does not supply their memory. They -retain their memory family when there are no live callers. Function-valued -fields retain their declared signatures in private summaries, avoiding repeated -unfolding of a constructor whose returned memory contains its own function field. -Class singleton initialization keeps its older store-at-exit implementation. - -## Partial references and readable fields - -`self` and incoming `C ^arg` parameters are incomplete references. `C? ^arg` -also accepts null. Ordinary functions and constructors accept the qualifier on -struct parameters; arrays cannot be qualified this way. - -- An allocation result is incomplete if any actual argument is incomplete. -- With only completed arguments, including null, the result is complete. -- An incomplete reference may be stored into self or passed to a `^` parameter. -- Ordinary calls and stores into other objects require completed references. -- A borrowed partial can read fields its incoming type proves initialized. - It cannot write fields, even non-finals. Exact local aliases of self retain - the original constructor's access to its current private memory. -- An object-reference field read through a partial is conservatively - incomplete, with no initialized-field guarantees for its referent. There is - no inference of initialized-field requirements on `^` arguments. - Arrays are already initialized and cannot receive - incomplete elements, so an initialized array field can be used normally. - -For example: - -```simple -struct Child { - Test.Parent? parent; - new Child = { Test.Parent? ^par -> parent = par; }; -}; -struct Parent { - Child child; - int~ payload; - new Parent = { int n -> - child = new Child(self); // Incomplete result: self is incomplete. - // Retention does not authorize reading parent.payload through child. - payload = n; - }; -}; -val parent = new Parent(arg); -val local = new Child(parent); // Complete argument, complete result. -return local.parent==parent; // Lookup is allowed. -``` - -Here `Test` names the source unit. After the root Parent constructor completes, -the entire cycle is usable: all members have initialized their own fields, and -none could expose an incomplete reference to ordinary code during construction. -The Child constructor still treats its `^par` as incomplete when the actual -argument is complete. This public constructor also has unknown callers, whose -partial arguments promise no initialized fields, so `par.payload` is unreadable. - -## Forward field views - -At a use of self, `InitViewNode` combines the pointer with that program point's -private memory. Its TypeMemPtr contains declared types for initialized fields -and Scalar.BOT for missing fields. The node retains the declaration separately -from the incoming flow shape, so an exact self alias captured before a Store -can receive a fresh view afterward. Earlier calls retain their earlier views. - -For example, a private helper can read `x` while `y` is still unset: - -```simple -struct _C { - int~ x; - int~ y; - new _C = { int n -> x=n; y=_read(self); }; -}; -val _read = { _C ^p -> return p.x; }; -return new _C(arg).y; -``` - -Parm meets the incoming shapes using the normal type flow. If any live caller -lacks `x`, Scalar.BOT survives and the Load reports the missing initialization. -Unknown callers supply an empty field promise. Parsing must also start borrowed -parameters at that bound: otherwise early folding of `p.x*0` could hide a bad -read before SCCP. The hidden constructor receiver retains its declaration; -its private memory supplies its read checks and precise field updates. - -Values still come from normal memory. Before a call borrowing self, EscapeNode -borrow slices carry the current constructor Stores onto the ordinary call -memory edge. These slices are aliasable and do not publish the private identity -or its fields into the global escape sets. No hidden partial-memory arguments, -field bitsets, additional passes, or recursive flow queries are introduced. - -InitView folds before TypeCheck when its input already has the same type and -retains a structural partial view. Nested partial-only Construct wrappers also -collapse. A Parm's current partial type alone is insufficient: inlining may -later substitute a complete actual argument, which must not grant the borrowed -parameter permission to write or publish that object. The completion form of -Construct already folds once its memory proves initialization and its result -type matches its input. - -TypeCheck checks the consumers and erases remaining InitViews along with the -checked Construct boundaries in its existing walk. A surviving field view is -not necessarily erroneous: a reader may need only the initialized subset. -Construct remains necessary for -final-field completion and for the partial qualifier of each source `new`. -Alias Phis and nested reference loads are conservative; they do not acquire -the original constructor's write permission. This prototype adds no general -ban on overlapping allocations of the same class: only the owning receiver -uses private memory, while borrowed reads use aliasable memory. - -## Aliases and loops - -Incomplete is a property of a value, not just the current contents of a parser -Var. Consider `while (n--) { use(p); p = self; }`: the backedge introduces an -incomplete value after `use(p)` has been parsed. `TypeMemPtr._partial` carries -that restriction through ordinary forward typing. It is an independent -two-point lattice: meet ORs the restriction and dual complements it. Copies, -conversions, Stores, and Phis preserve it; a merge is incomplete if any live -input is incomplete. A `^` formal stays incomplete even when its known callers -are complete. The receiver's private memory identifies the own-self exception; -another incomplete pointer of the same class has no such permission. - -A small `ConstructNode` wraps each source `new`. Its runtime value is the -allocator result; its type adds the OR of that call's actual argument qualifiers. -This distinguishes `new Child(self)` from `new Child(null)` even when both call -the same constructor. Looking only at the shared callee Return would lose this -distinction. The node disappears after TypeCheck, before lowering. - -A completed receiver gives a completed view of its pointer fields. Construction -may retain incomplete references but cannot publish them, so reaching the root -`new` boundary with complete arguments makes the entire reachable cycle usable. -There is no group identity or traversal to mark members complete. Conversely, -object-reference fields read through incomplete self remain conservative, even -if the particular stored reference was complete. - -The existing optimistic SCCP solve also handles qualifier cycles. For -`p = null; while (n--) p = new Link(p);`, no input introduces incompleteness, -so `p` stays complete and a subsequent field read is allowed. A backedge carrying -self instead makes the Phi and its uses incomplete. - -`Construction` selects private self memory during parsing; it retains no -source-use lists or flow facts and performs no recursive Load/Phi/Call query. The old -root and allocation bitsets are gone. There are no field-requirement sets, -hidden `^` memory arguments, or runtime group objects. - -`PartialReadTest` exercises field reads, missing fields, forwarding, merged -callers, loops, exact aliases, constructor retention, and borrowed write and -publication restrictions. `ConstructionGroupTest` exercises cycles, complete/null arguments, prohibited -lookups/publication, aliases, branch merges, complete and incomplete loop -backedges, and declared restrictions with only complete callers, including an -uninlined constructor through machine encoding. `ConstructorCompletionTest`, -`FinalConstructionTest`, and `BoundaryTest` exercise field-memory semantics. -The former inferred-requirement litmus tests are preserved, explicitly deferred, -in `ConstructionRequirementsTest`. Separate compilation of `^` functions is -still deliberately unsupported. The pointer qualifier has an object-file -representation, but importing and checking the full construction contract is -outside this experiment. Rebuild chapter 29 object files after the type-format -change. - -## Deferred field-aware contracts (2026-11-07) - -Decision: do not implement inferred contracts now. Cliff considers the required -infrastructure too large for the feature alone; revisit when a general -backwards/liveness flow is justified, potentially for memory management. -The later forward-field-view prototype above does not implement this contract -discovery proposal. Separate compilation of `^` interfaces remains rejected. - -The intended extension would let functions and constructors receive partially -initialized objects, read initialized fields, retain partial references with -their restrictions, and write non-final fields. Only the original constructor -would retain permission to initialize/reassign its own final fields; passing a -pointer must not pass that permission. Final-field reads during construction -would not establish value stability against later writes by that constructor. - -The proposed contract representation uses normal types, not a separate field -bitset. For a function reading only `P.pi`, its unknown-caller default would be -schematically `Partial{pi:declared-pi-type, name:TypeScalar.BOT}`. Scalar.BOT -means no initialization guarantee, not a requirement that the caller leave the -field unset. Required fields receive their declared types, covering every legal -external caller. MEET with actual arguments preserves those guarantees only -when the callers satisfy them; extra initialized fields supplied by locals do -not strengthen the body beyond the external contract. TypeStruct/Field already -meet field contents, and nested/cyclic types can represent nested contracts. -TOP is not the missing-initialization marker. - -Cliff proposed discovering conservative, context-insensitive requirements after -Iter and before SCCP. Freeze the resulting default argument types on functions; -SCCP consumes them without refining the contracts. Reads on branches SCCP later -eliminates may still impose requirements, as may reads following assignments. -That rejection of some valid programs is acceptable for an opt-in `^` feature. -Combine compatible requirement shapes with JOIN; combine possible caller states -with MEET. Keep the contract distinct from the merged Parm type, and check each -actual argument against it for a call-site diagnostic such as -"foo requires Partial.pi to be initialized". Serialize contracts with declaration -metadata so checking imported calls does not require loading bodies. - -The complication is discovering and propagating those contracts. Local SSA -aliases share values; Phi demands reach every input. A demand on a loaded field -becomes a nested receiver requirement. Calls substitute actual arguments for -formals, and recursive forwarding needs a convergent propagation rule. Cyclic -types represent recursive requirements but do not by themselves prevent a -discovery algorithm from unfolding progressively deeper paths. Indirect calls -need contracts available through their callable interfaces; returns need usable -guarantees without retroactively strengthening an exported contract for a client. -Stored references and helper writes also require a coherent account of private -construction memory and object identity; that discussion was deliberately left -unfinished. None of this requires H-M or bidirectional type inference, but it -does require a substantial backwards demand analysis to handle well. - -The ignored ConstructionRequirementsTest retains useful litmus cases, not an -approved implementation plan. Do not restart this work without a new request. diff --git a/chapter30/docs/deferred-construction.md b/chapter30/docs/deferred-construction.md deleted file mode 100644 index 104ab9e9..00000000 --- a/chapter30/docs/deferred-construction.md +++ /dev/null @@ -1,385 +0,0 @@ -# Deferring construction checks: experiment - -The [escape-flow continuation](escape-flow.md) supersedes the frozen-public -fallback and remaining recursive-test failures described later in these notes. -All four recursive examples now pass their original printed-IR expectations. -The older audit below records the evidence that led to this change. - -The extra construction pass is removed from the working implementation. -`Construction.check()`, its retained source-use lists, `Iter.types()`, and the -separate constructor-Return walk are gone. Errors now belong to the existing -TypeCheck walk; ConstructNode retains final private memory for completion checks. -No additional whole-graph pass was added. Constructor rejection tests remain active. - -## Constant folding - -`TypeScalar.BOT` is not an initialized integer. Arithmetic, comparisons, -negation, numeric conversions, and typed Stores must preserve it rather than -manufacturing an integer or floating-point result. In particular, `x*0` and -`x==x` cannot become constants while `x` has this type. An initialized unknown -integer still permits those folds. - -The scan found and changed these related cases: - -- Multiplication by zero now folds in `compute`, after checking numeric inputs. - Integer strength reduction also waits for integer operands; an unfinished - loop Phi could eventually become a float. -- Same-input comparisons fold in `compute`. Floating comparisons keep NaN - semantics; `x==x` is not necessarily true. The integer range implementation - of `!=` also had the equality answers reversed. -- Arithmetic pushed through Phis uses each copied operation's `compute`, - including floating-point constants, instead of an unchecked integer cast. -- Known array length offsets and element shifts fold in - `ConFldOffNode.compute`, rather than its `idealize`. -- `Not`, unary minus, conversions, and Stores preserve unknown initialization. - `RoundF32` already passed that type through. - -This does not ban creating constant *operands* in rewrites such as `x*8` to -`x<<3`. Memory forwarding still has cases that return a stored constant or an -array's zero-filled element; these were inspected but not rewritten into a new -memory analysis. `Load.idealize` retains a `Scalar.BOT` load. - -The changes exposed a rejected-Phi-fold worklist cycle. Factoring -`Phi(bool & 7, integer & bool)` widens the result from `bool` to `[0-7]` and -must fail. Building and then killing the candidate woke the same dependencies -forever. The trial now computes its types before registering use edges. - -## Preserving the constructor body through optimization - -This regression must reject a live incomplete lookup: - -```simple -struct Child { - Test.Parent? parent; - new Child = { Test.Parent? ^par -> parent = par; }; -}; -struct Parent { - Child child; - int~ payload; - new Parent = { -> - child = new Child(self); - payload = child.parent == null; - }; -}; -return new Parent().payload; -``` - -`child` is incomplete because its constructor received incomplete `self`. -Reading `child.parent` must therefore fail. The read supplies the final result; -this is not a discarded local or dead-code issue. - -The decisive failure was private-memory Parm typing. During Iter, inlining -removed a real caller while the function still had its unknown-caller edge. -The special case returned MemTop anyway. That erased the memory merge, Store, -and the bad Load feeding it, before TypeCheck could report the error. - -Parms now use their normal merge. Hidden initializer/constructor helpers have -only actual allocator callers; the source-visible constructor binding denotes -the allocator. Public allocators still receive unknown callers, so unused public -constructor bodies remain checked. This also avoids poisoning a helper's private -memory with a fictitious external default. - -Inlining presents a second issue: a complete actual pointer must not grant -permission to read a restricted formal. A partial-only ConstructNode gives -self and ^ parameters their body view independently of Parm typing. It remains -until TypeCheck. Load's alias search recognizes that this view preserves the -address, while compute/err continue to see the qualified pointer. - -A smaller regression reads an unwritten field through a self cycle: - -```simple -struct C { - C next = self; - int~ x; - new C = { -> x = next.x; }; -}; -return new C().x; -``` - -Both examples now reject at TypeCheck. A positive regression initializes x to -7, increments it in the constructor, and checks that the result folds to 8. - -The broader run exposed a function-lifetime bug during SCCP: unlinking calls -could delete a body subsequently rediscovered from a type-level function -reference. Returns are kept during the existing reset walk and released once -call edges have been rebuilt. No additional graph walk is needed. - -Class-init dependency discovery also skips a CLInit whose receiver has not -resolved to a class. A Scalar.BOT receiver is left for its Load's TypeCheck -error, rather than dereferencing a null class name. - -The trial successfully uses the existing passes to prove a chain built from -`null` complete. It also rejects direct `par.payload`, `par.payload*0`, and -`int x = par.payload; value = x*0` after the arithmetic/conversion repairs. - -Genuinely unused reads are allowed to disappear under late-check semantics. -Rejection tests must keep the read live. `testUnusedIncompleteReadCanDie` checks -that an unused `par.payload` read is eliminated and the program returns 5. - -## Optimization differences and register allocation - -`Chapter18Test.testFcn9` exposed an independent escape bug. StopCU treated the -class initializer's synthetic self as an object already held by an external -caller. Its broad function-valued field type exposed the local x function even -though the initializer never returned and x had no callers after inlining. -Skipping that synthetic argument restores the empty escape set for x and the -expected `return Top;`. Actual public-call arguments still escape normally. - -That correction exposed `Chapter18Test.testFcn8`: a Store computed from TOP -memory interpreted its optimistic singleton bit as established private memory. -It widened a function value to the declared signature, then narrowed its FIDX -set when memory resolved. Store now returns TOP while its memory is TOP, so -SCCP remains monotone. - -The String differences have a different cause. In Chapter19, the private -_hashCodeString body dies; the surviving functions are the initializer, -allocator, equals, and public hashCode. Its golden string now omits the two dead -private-helper MemTop Returns and matches the current addition order. -`Add.spine_cmp` breaks this tie by node ID. Strength reduction creates the Sub -in IterPostOpto, after the byte Load (Sub#594 versus Load#504 in one traced copy), -so the Sub sorts to the left. This is node ordering, not a lost value type. - -In the Chapter20/21 fixtures, _hashCodeString really escapes through the implicit -return, and hashCode contains an inlined copy. Before the allocator repair, both loops needed an extra x86 -register copy with the new addition operand order. A disposable probe -swapped only `((hash<<5)-hash) + byte` to `byte + ((hash<<5)-hash)` after Unlink: -no types or live functions changed, but the weighted split score fell from 37 -to 21. Each hash body fell from 17 to 9; the allocator stayed at 3. - -Reconstructing the earlier source by reversing the saved construction-pass -removal patch reproduces the expected 29. Its standalone _hashCodeString costs -17, inlined hashCode costs 9, and allocator costs 3. Before the allocator repair, -these costs were 17, 17, and 3. Both versions contain two hash loops; no inlining decision changed. -Current code emits two fewer functions, the dead initializer/constructor helpers, -which contributed zero. Thus the entire increase is one loop-weighted register -copy in the inlined hashCode body, not another retained function or stack spill. - -With the old operand order, the byte Load can write the loop's hash register -and Add accumulates the shifted/subtracted value into it. With the new order, -Add's destructive input is the Sub result. Its two-address tie plus the Phi -backedge joins the shift/Sub/Add chain to the old hash live range, which overlaps -the shifted value at the subtraction. `RegAlloc.splitSelfConflict` inserts a -`use/self/two` copy before Add. The existing commute heuristic in `splitByLoop` -is not reached: self conflicts take an earlier splitting path. Commuting Add -before splitting is the concrete optimization opportunity. - -The allocator now does this in `splitSelfConflict`, using the existing failed- -range traversal and scratch list. It commutes two-address operators when the -RHS has one use and belongs to a different live range, then omits the copy for -the tie it broke. An allocator-generated Split is excluded: its single use can -hide a longer-lived value, and commuting onto it can undo an earlier repair. -The existing coloring retry rebuilds live ranges. There is no new whole-IR pass -or analysis structure. The machine's `commutes()` hook covers Add, Mul, Xor, -And, and Or (and commutative floating instructions). - -The String score is now 21: each hash body costs 9 and the allocator costs 3. -The three x86 expectations are updated to 21. A single regression exercises -all five integer operators in both machine operand orders, checks register -constraints, and encodes the results. Existing testFlags2 guards against the -Split-operand regression. - -## Incremental Iter setup - -Iter no longer resets and requeues the whole graph after parsing. `Node.init()` -queues initialized nodes, and Calls queue themselves so Iter can link targets -loaded after the call was parsed. Iter seeds its new global escape summary, -then drains the worklist. Import loading still resets the newly loaded nodes -and repairs affected neighbors. - -Removing the sweep also exposed an unused receiver left behind when field -lookup switches from an instance to its class. That path now releases the keep -and kills the receiver if unused. - -FldOffNode's base is data in slot 1. Slot 0 is reserved for control; putting a -data parameter there made inliner body discovery exclude an unresolved offset. -The regression `CallEndTest.testUnresolvedOffsetInInlineBody` checks that the -offset belongs to the function body even before its type resolves. - -## Type upgrades in Opto setup - -ParseAll still closes the named types and freezes the public interface after -loading all units. It no longer walks the IR. Opto installs those closed types -and resolves forward references during its existing reset walk. Setup runs no -peepholes against the partly reset graph: resolved FRefs propagate their input -type in SCCP and disappear during subsequent peepholes. Construction identities -also wait until this setup has installed complete field declarations. - -That walk retains Returns while call edges are rebuilt, gathers unresolved -numeric modes, and records dependencies for cleanup after SCCP. Type upgrades -also register cleanup dependencies, even if the eventual value type is unchanged. -Old Iter types are snapshots for change detection, not upper bounds after -recursive declarations have been closed. SCCP still asserts monotone falling -types and a complete worklist within its own solve. - -The move exposed assumptions formerly hidden by early upgrades. Resolving an -already known class name must retain its known fields instead of replacing them -with an empty placeholder. A Load must not forward a stored pointer whose open -shape is weaker than the Load's computed type. Escape must retain escapes from -the actual private value before narrowing it to its declared field type, so -selecting a Store out of a MemMerge does not introduce new escapes. - -An unknown return or memory effect carries FULL escape sets. StopCU and -GlobalEscape preserve that bound: narrowing it to public names would omit -private objects and callbacks that a subsequent load-forwarding rewrite can -reveal. Both summaries recompute from their inputs without retaining previous -escape sets. Refining a value removes possibilities; it never adds escapes -outside the old bound. IterPeeps has no special summary handling, and its -worklist assertion requires every node's type to lift, including queued nodes. -`testUnknownEscapesRefineToPrivateValues` checks both escape sinks; -`testPrivateRecursiveReturn` covers cyclic private objects and field loads. - -The ordinary dependency mechanism also covers signature refinement and lazy -imports. FunNode depends on its Return when refining its signature. Calls -depend on their target FunNode; while a target is absent, they depend on Start -and retry when a linker mapping is installed. Loading bodies and adding call -edges still use `Iter.repair` for graph changes, not for value refinement. - -SCCP's Start linking honors FULL for private targets too. Incoming arguments -are not themselves outgoing escapes; Stores, Returns, and external-call -arguments describe those effects. Constant singleton field slices carry the -stored value's escapes, not unrelated bulk-memory escapes frozen at the time -of folding. This preserves precision for local recursive callbacks. - -As bounds sharpen after SCCP, FunNode removes unknown callers even if concrete -callers remain. Called initializers retain their Return through StopCU because -CLInit has no Return edge. Removing an uncalled function queues the affected -Stops, and compilation-unit wrappers retain distinct identities even when -empty. These are worklist notifications and ownership rules, not extra passes. - -### Remaining precision issue with FULL escapes - -The monotone bounds expose a feedback problem in the existing grand cycle. -In `Chapter12Test.testPrivateRecursiveReturn`, SCCP sees BOTTOM for the final -load chain and therefore FULL escapes. These feed through Start's memory into -the function memory results. Post-SCCP forwarding resolves the return to `_B`, -but that memory cycle remains at MemBot and keeps private constructors callable -by unknown callers. This is conservative, but loses the previous dead-function -elimination. It does not justify narrowing BOTTOM to public names or adding -the IterPeeps widening repair back. - -For this example, the root Return goes from `[Ctrl, MemBot, Bot]` after Opto to -`[Ctrl, MemBot, *_B]` after TypeCheck; Stop's memory remains MemBot. The remaining -design question is how to avoid this feedback while retaining conservative -bounds and the existing pass budget. The current experiment leaves the printed -IR expectations unchanged so they continue to expose this loss of precision. - -The source-validity audit separates these cases from Chapter10 `testIfOrNull`. -That test originally returned the nullable pointer itself. A historical edit -changed it to `return bar.a;` without adding TypeCheck, leaving a real null -error hidden behind a printed-IR assertion. It now again returns `bar`, runs -through TypeCheck, and passes with `return Phi(Region,null,Test._Bar);`. - -All four remaining programs pass TypeCheck. The Chapter12 recursive-object -tests have one pending bad Load after Opto; forwarding eliminates every Load -and resolves the result to `17`, `_B`, or `_R`, while escape memory stays MemBot. - -The two Chapter17b forward-type tests now pass their original IR expectations -and explicitly run TypeCheck. Their undeclared `B` is an opaque external type, -not an arbitrary unknown local value. EscapeNode uses the frozen public -interface as its fallback for that type, preserving escapes already present -in its private and public memory inputs. This applies to both the actual private -value and the declared field bound: in `testForward1`, the private array element -type is already `B?`. Bounding only FIDXs is insufficient; FULL aliases expose -private class fields, which then expose their constructor FIDXs. - -CodeGen caches the fallback when ParseAll freezes the public interface. It -returns FULL until Opto's existing reset walk installs the closed types into -the IR. Only then does an open `_fref` reliably denote an external object. -Ordinary open local structs, `TypeScalar.BOT`, and abstract pointers still -require FULL. No new pass or IterPeeps hook is involved. - -### Escape-bound audit - -All Chapter29 `escapesFrom`, `XInt.FULL`, and `TypeMem.BOT` uses were reviewed, -including the equivalent `escapes` helper and indirect `makePrivate` uses. -The following remaining sites warrant work; they have not been narrowed here: - -* **StoreNode's three `escapesFrom(val)` paths.** The singleton constant, - private instance, and ordinary aliasing paths still treat an opaque external - value as FULL. A concrete example is: - - ```simple - struct _A { B? !b; new _A = { B? p -> b=p; }; }; - val wrap = { B? b -> return new _A(b); }; - return wrap; - ``` - - This passes TypeCheck, but the surviving Stores of `b` have FULL FIDX and - alias sets and keep an extra `_A` allocator. Do not mechanically substitute - the public default: singleton slices deliberately discard unrelated incoming - memory escapes. A narrower opaque bound must retain private values previously - given to external code, without freezing unrelated transient escapes into - singleton constants. Ordinary aliasing Stores already retain incoming sets. - -* **StopCU return values, CallNode external arguments, and SummaryNode arguments.** - These use `escapes`, which currently duplicates the unbounded `escapesFrom`. - `val identity = { B? b -> return b; }; return identity;` passes TypeCheck but - gives StopCU MemBot. Likewise, - `val send = { B? b -> { B? -> int } retain = "C"; return retain(b); }; return send;` - gives the native CallEnd MemBot. These are concrete instances of the same - opaque-type precision loss. A future change can share the bounded helper, - while retaining incoming/returned memory, explicit private arguments, and - imported-summary effects. StopCU's public function seed and `escapesAliases` - class seed describe known declarations; GlobalEscape's `escapes` calls merely - union already computed TypeMem sets. - -* **CLInitNode's possible-initialization result.** Even a known initializer - yields TypeMem.BOT until its ready flag is true; only the initialized flag's - slice is precise. This loses both memory-content and escape precision. - CLInit has an analysis call edge but no Return edge supplying callee effects. - Improving it needs a dependency on the initializer's effects, including - recursive dependencies. The public interface alone is not a safe cap: that - initializer can publish private callbacks. Its unresolved-flag BOT fallback - is also conservative, but normally disappears when the receiver resolves. - -* **CallEndNode's unknown or unlinked target result.** Both return TypeMem.BOT. - The unlinked case covers invalid calls and transient missing edges; SCCP links - valid finite targets before computing CallEnd. Truly unknown targets can be - local private functions as well as external functions, so a public-only cap - would be wrong. Native calls already use CallNode's argument/memory effects. - Any refinement must distinguish target provenance and retain explicit private - arguments; it is not the same small fix as an opaque external object. - -The other broad defaults appear justified: - -* TypeMem's generic BOTTOM/scalar/pointer cases and TypeStruct's unknown scalar - fields must include private callbacks that later value refinement can reveal. - Private-memory declarations/Phis use `makePrivate(BOTTOM)` for the same reason. - MemMerge's `makePrivate(struct)` describes actual fields, not an external - opaque object. -* Parser/function memory declarations, initial node types, TypeTuple.STATE, - and low-family error fallbacks in Store, MemMerge, BulkMemPhi, Start, and - TypeTuple need worst-case memory. CallNode and SummaryNode likewise cannot - promise bounded effects when their inputs are still arbitrary low values. -* Iter's import reset gives newly loaded nonconstant memory FULL before repairing - affected neighbors. Saved types belong to another caller context; constants - retain their own computed types. This is a safe pessimistic seed, though it - can contribute to the existing memory-cycle precision problem. -* TypeFunPtr's FULL signatures and TypeRPC.BOT describe unknown function/return - targets. Serialization/remapping preserves the FULL sentinel; type gathering - exercises it; LoopNode's `isa(TypeMem.BOT)` is a type-family check. These do - not independently manufacture an escape effect. - -Ignoring assertions, the remaining whole-node walks through TypeCheck are -Opto's setup/reset and TypeCheck's error scan. Class-init checking separately -scans function control flow and runs SCC over the resulting dependency graph. - -## Validation - -Chapter29's latest run tested 594 active cases with assertions: 590 passed and -four printed-IR comparisons failed. `make -k tests` ran raw0 (400/404), raw1 -(38), standalone (13), system (29), and fuzzer (1); the aggregate group (109) -was run separately because Make skips it after a prerequisite failure. -The remaining failures retain extra private constructors: Chapter12 `testCoRecur`, -`testCoRecur2`, `testCoRecur3`, and `testPrivateRecursiveReturn`. Both Chapter17b -forward tests pass unchanged goldens. TypeTest.testOpaqueExternalEscapes checks -both fallback sets, preservation of prior private escapes, and FULL for ordinary -unknowns. System, spill, import, callback, and constructor tests pass. The only -golden changed during the earlier source-validity audit belongs to the restored -`return bar;` source; none were changed to accept extra functions. - -The offset regression fails with the old slot-0 layout. Constructor and -boundary tests pass, including both missed rejections and the prior NPE. -Printed-IR expectations omit the dead private-helper MemTop Returns; no -rejection expectations were relaxed. The three String spill checks now expect -21 on x86, with the same live functions and inlining decisions. diff --git a/chapter30/docs/escape-flow.md b/chapter30/docs/escape-flow.md deleted file mode 100644 index 8ad49f15..00000000 --- a/chapter30/docs/escape-flow.md +++ /dev/null @@ -1,147 +0,0 @@ -# Outside-world escape flow - -The `escape-flow` branch developed this design in Chapter29 and backported it -to Chapters 28a/28b. Chapter28a uses `LocalIds` and its existing initializer -root/lowering protocol; Chapter28b adds saved summaries and cofinite identity -remapping. Neither port imports Chapter29's deferred-construction model. - -## The cycle - -The outside world's access to local objects and functions is a value in the -Start/Stop cycle. Public declarations are not that value. The frozen public -interface inventory has been removed; public-method and public-alias tests -check the converged outside escape sets directly. - -At Opto setup, the outer Start receives a constant foreign-identity seed: - -``` -foreign identities = FULL minus identities owned by this compilation -outside identities = foreign identities union discovered local escapes -``` - -Known native function and storage identities are foreign too. The infinite -tail permits future foreign functions even when no local callback has escaped. -The finite exclusions include registered imported identities, including bodies -represented by summaries. This scans identity tables, not the IR. Opto's -existing reset/worklist solve discovers the local escapes. - -StartCU includes the shared outside state. Infinite FIDX sets must retain their -exclusions: `Opto.linkStart` checks each local function's membership rather than -treating every cofinite set as FULL. Serialization remaps a cofinite set by -remapping its finite exclusions and complementing again. - -Before Opto, outside queries remain pessimistic. During SCCP, a consumer can -read the foreign seed before Start has run: otherwise a temporary finite set -can turn a generic foreign callback into an unrelated local function with the -same arity. No previous escape result is accumulated to repair value flow. - -## Consumers and dependencies - -* Memory and callback defaults for unknown callers use Start's memory - projection. Parm applies its declared callback signature to the escaping - FIDX set. Defaults whose values do not depend on escapes remain constants. -* Unknown/native CallEnd results use the outside state and the current call's - exposed arguments. Callback results are bounded by their declared signature - and the outside FIDX set. Explicit linked Return effects are retained. -* CallEnd registers a direct dependency on Start. Depending only on Call is - insufficient: Call can stay CONTROL while the outside set changes. This - first implementation uses `addDepForwards`; it does not change CallEnd's - input layout or introduce a synthetic Fun/Return pair. -* Infinite calls use the outside continuation. Escaped local functions remain - callable through Start, and their effects return through Stop. Attaching - every same-arity body to an infinite call is incorrect: argument/result - families may differ despite the equal arity. -* Outgoing Call argument exposure is independent of CallEnd, including a call - that never returns. The shared fixed point also permits immediate callback - round trips and reentrant calls. -* Opaque external values in Escape, Store, Return, and imported-summary paths - use the current outside/input-memory bound. Explicit private values and - already accumulated escapes remain included. Arbitrary local BOTTOM values - still require FULL. -* Function-valued Loads use their memory input's FIDX bound, joined with the - field declaration. They do not independently manufacture an escape set. - -CLInit was another unconditional producer of FULL. During Opto it now depends -on the known initializer's Return and merges those effects with incoming -memory. It waits for live memory before publishing effects. Lowering computes -the replacement CallEnd's linked type before exposing its projections, so a -temporary unlinked MemBot cannot widen the already analyzed caller. - -## Why the recursive tests needed local precision too - -All four former Chapter12 printed-IR failures pass their original expectations. -The problem was not solely an outside-call default: - -1. Convert widened a non-null pointer to a nullable declaration until its later - identity rewrite. It now preserves non-nullness in compute. Preserving the - entire source shape conditionally failed the existing monotonicity test; - shape and access still follow the declaration. -2. A Load could wait until post-SCCP Store forwarding to recover that non-null - pointer. In the meantime the next dereference produced BOTTOM, which fed - FULL around the memory cycle and revived private constructors. -3. Forwarded addresses, resolved field aliases, and already-bypassed CLInit - projections were also waiting for graph rewrites. - -Load's existing forwarding search now supplies pointer value facts during -compute, without constructing or rewriting nodes. It can recognize a stored -address through a valid pointer conversion or a proven forwarded Load, use a -resolved named field before layout, and follow an existing CLInit bypass. -The same dependency mechanism reruns the search when its evidence changes. -Nullable/incomplete access checks still precede this sharpening; arbitrary -memory Phis and unknown stores remain barriers. This adds local queries, not a -new whole-program pass, analysis map, or second IR. - -## Hidden class receivers - -A class function's hidden `#self` defaults to its owning class singleton. -Seeding that input with TypePtr.PTR used to give FULL escapes when forwarded -to an unknown callback. For example: - -```simple -val _hidden_noInline = { int n -> return n+2; }; -val apply_noInline = { {int->int} f,int n -> return f(n); }; -return apply_noInline; -``` - -`FunNode.defaultArg` now supplies the Test class singleton for this receiver, -both during parsing and when Opto reconnects unknown callers. The callback -parameter still reads Start dynamically. The printed-IR regression verifies -that only `` and `apply_noInline` escape; `_hidden_noInline` stays private. - -The function signature retains TypePtr.PTR in this slot. The backends use it -to identify the hidden ABI argument, and callback annotations must not bind -the receiver to the class where the annotation appears. Explicit calls still -supply their actual receiver; instance methods keep their declared object -type. This sharpens the default input, not every abstract pointer: a local -merge of a private object and private callback can also have an abstract -pointer type, so capping arbitrary TypePtr values at outside escapes is unsound. - -## Remaining design question - -Late imported identities also deserve further precision work: identities not -registered when Opto starts lie in the foreign tail. Existing import tests -exercise correctness, but this can remain conservative when bodies arrive -later. This limitation is not repaired by resetting the whole IR. - -## Validation - -The combined `make -k tests CHAPTERS="chapter28a chapter28b chapter29" CTAGS=` -run passes with assertions: 538 active tests in Chapter28a, 578 in Chapter28b, -and 601 in Chapter29. Shared printer and ISA checks pass too. The log is saved -under ignored `build/escape-backport-final.log`. - -`EscapeFlowTest` covers opaque wrappers with three worklist seeds, foreign -callback parameters, private callbacks passed to and returned from native code, -and a CallEnd dependency that responds when only Start's escape set changes. -It also checks that public allocators escape while their private-memory helpers -do not. Class-init tests cover unknown callback cycles; saved-library tests in -28b/29 verify private-function exclusions survive identity remapping. -The existing suites cover nonreturning native calls, class-init cycles, -constructor rejection, serialization, imported callbacks, and three backends. -The four recursive-class examples also pass a separate 16-case worklist-seed -check. Backport IR expectations now retain public allocator Returns instead of -private-memory helper Returns. The String allocation/encoding/export fixtures -in 28a/28b/29 now declare `_hashCodeString` before the public `hashCode` wrapper, -so the implicit return exposes the wrapper. Their measured spill expectations -are 12/8/6 (x86/RISC-V/ARM); native x86 export expects 12. The reordered fixture -also measures 8 on RISC-V before the backport, versus the old order's 6. diff --git a/chapter30/src/main/java/com/seaofnodes/simple/parser/Construction.java b/chapter30/src/main/java/com/seaofnodes/simple/parser/Construction.java index 6dec8ac1..7797cae4 100644 --- a/chapter30/src/main/java/com/seaofnodes/simple/parser/Construction.java +++ b/chapter30/src/main/java/com/seaofnodes/simple/parser/Construction.java @@ -56,7 +56,8 @@ import com.seaofnodes.simple.util.Ary; * binding denotes the allocator. Private-memory Parms therefore need no * fictitious external default or constructor-specific transfer function. * InitView and Construct are erased by the existing TypeCheck walk. There is - * no extra construction pass; see docs/construction-groups.md. + * no extra construction pass; see chapter29/docs/construction-groups.md + * from the repository root, and chapter29/README.md for the introduction. */ final class Construction { private final Parser P; diff --git a/chapter31/README.ja.md b/chapter31/README.ja.md index 9f264ae2..190245a2 100644 --- a/chapter31/README.ja.md +++ b/chapter31/README.ja.md @@ -8,13 +8,18 @@ Simple で描画する `sys.draw.Canvas` と、MiniFB を使うオプションの ウィンドウ・入力 API `sys.gfx` を使って、グラフィカルな三目並べを実装します。 矩形、円、太い線、色、ビットマップ文字を扱えます。 -詳細は[英語版の描画ライブラリとゲームの説明](docs/drawing.md)を参照してください。 +詳細は[英語版の描画ライブラリとゲームの説明](src/main/smp/sys/draw/README.md)を参照してください。 通常のビルドとテストに MiniFB や画面表示は必要ありません。 ```sh -make -C chapter31 run-graphical-tictactoe CTAGS= +make -C chapter31 run-graphical-tictactoe ``` +`%` は Java の `%` と同じ符号規則を使う剰余演算子です。`*`、`/` と同じ優先順位で、 +左から右に結合します。例えば `-17 % 5` は `-2`、`17 % -5` は `2` です。 +整数と浮動小数点数に対応し、整数のゼロ除算は Simple の `/` と同様にゼロを返します。 +詳しい意味と実装は[英語版の説明](README.md#remainder)を参照してください。 + このスナップショットの[文法](docs/31-grammar.ja.md)と [実行可能な例](docs/examples/)を用意しています。 ビルド手順は[英語版](README.md)を参照してください。 diff --git a/chapter31/README.md b/chapter31/README.md index ff40999a..0b46ea68 100644 --- a/chapter31/README.md +++ b/chapter31/README.md @@ -11,6 +11,10 @@ a few games, with the drawing and game logic written in Simple. ## Games and demos +All graphical demos support resizing. Canvas scales their base layouts and +mouse coordinates together, preserving proportions; Breakout's physics remains +in base coordinates. The pixel gradient fills the resized window. + [Clock](docs/examples/Clock.smp) is a classic clock demo. It shows local time as digital digits or an analog dial. Click its button or press Space to switch views. It combines timers, mouse input, text, and drawing in one event loop. @@ -28,6 +32,36 @@ brick gives a one-time larger speed boost. Clear all the bricks before using up three balls. +## Remainder + +`%` computes remainder with Java's sign convention. It has the same +precedence as `*` and `/`, and associates left to right. For example, +`17 % 5` is `2`, `-17 % 5` is `-2`, and `17 % -5` is `2`. +The remainder follows the dividend's sign; it is not always nonnegative. +Integer `MIN_I64 % -1` is zero. Like Simple's integer division, integer +remainder by zero produces zero. Unused arithmetic can be removed. + +Floating-point operands use the same truncating-quotient rule: `7.5 % 2.0` +is `1.5`. A zero divisor or infinite dividend produces NaN; a finite dividend +modulo infinity is unchanged, and a zero result retains the dividend's sign. +Mixed integer/float operands convert to floating point, as with `*` and `/`. +The compound assignment `x %= y` stores `x % y` back into `x`. +`mod` is an ordinary identifier. + +Clock uses `second % 10` for its last digit and `i % 5 == 0` for major +dial ticks. The time library uses the operator for leap years and calendar +fields, adding a positive period when it needs a nonnegative result. + +[`ModNode`](src/main/java/com/seaofnodes/simple/node/ModNode.java) follows +`DivNode`: two operands, one result, and shared arithmetic folding and type +checking. It has no control or memory effects. Integer machine encodings handle +zero divisors and signed overflow to preserve the ideal operations' results +without hardware faults. Floating remainder uses a memory-preserving runtime +helper selected as a machine operation; the ideal graph stays ordinary arithmetic. +`make test CLASS=ModTest` covers folding, evaluation, native execution, imports, +and code generation for all three targets. + + ## Graphics and sound Graphics and sound are optional. The Simple language and compiler do not need @@ -55,8 +89,8 @@ timeout, so animation need not spin continuously. optional miniaudio backend plays sound while the game continues. The games can run silently when audio is unavailable. -See [drawing](docs/drawing.md), [windows](docs/graphics.md), and -[audio](docs/audio.md) for the APIs. +See [drawing](src/main/smp/sys/draw/README.md), [windows](src/main/smp/sys/gfx.md), and +[audio](src/main/smp/sys/audio.md) for the APIs. ## Time library @@ -84,7 +118,7 @@ sys.io.p("UTC %tT(sys.time.now())\n"); Millisecond parameters and fields end in `_ms` to distinguish them from other integers. -See [time and timers](docs/time.md) for local-time formatting and other forms. +See [time and timers](src/main/smp/sys/time/README.md) for local-time formatting and other forms. ## Array initializers @@ -124,25 +158,86 @@ read-only array of two non-null, read-only strings. ## Math support and intrinsics -[`sys.math`](src/main/smp/sys/math.smp) provides the `PI` and `E` constants, -plus two operations: +[`sys.math`](src/main/smp/sys/math.smp) provides `PI`, `E`, `min`, `max`, and +five native math functions, each with signature `{ f64 -> f64 }`: + +| Function | Result | +| --- | --- | +| `sin(x)` | Sine of an angle in radians | +| `cos(x)` | Cosine of an angle in radians | +| `exp(x)` | e raised to x | +| `log(x)` | Natural logarithm of x | +| `sqrt(x)` | Nonnegative square root of x | ```simple -i64 bits = sys.math.f64Bits(1.0); // 0x3ff0000000000000 -f64 value = sys.math.f64FromBits(bits); // 1.0 +f64 diagonal = sys.math.sqrt(2.0); +f64 height = sys.math.sin(sys.math.PI/6.0); +f64 power = sys.math.exp(2.0); +f64 exponent = sys.math.log(power); ``` -They *reinterpret* the same 64 bits, preserving signed zero and NaN payloads. -Ordinary assignments between integer and floating-point types still perform -numeric conversion. +These are direct bindings to the host's libm; the standard linker already +includes `-lm`. Results and domain/range errors, including `errno`, follow +that library. See the native references for +[trigonometry](https://sourceware.org/glibc/manual/2.43/html_node/Trig-Functions.html) +and [exponents, logarithms, and square roots](https://sourceware.org/glibc/manual/latest/html_node/Exponents-and-Logarithms.html). +They remain ordinary C calls, so they are not constant-folded or discarded as +pure intrinsics. Clock uses `sin` and `cos` for its dial and hands. +`make test CLASS=MathTest` checks native results, special values, indirect calls, +and code generation for all three targets. -These functions introduce compiler intrinsics: C functions with fixed meanings -that the compiler recognizes and replaces with internal operations. For the -bit-reinterpretation operations, Simple uses plain register moves. Calls whose -targets remain unknown at compile time use the C implementations. Recognition -and expansion live in `Intrinsic.java`. +Two representation operations are compiler intrinsics: -See [the intrinsic contract](docs/intrinsics.md) for the implemented behavior. +```simple +i64 bits = sys.math.f64Bits(1.0); // 0x3ff0000000000000 +f64 value = sys.math.f64FromBits(bits); // 1.0 +``` + +They *reinterpret* the same 64 bits, preserving signed zero, infinities, +subnormals, and NaN signs and payloads, including the signaling bit. They perform +no arithmetic and have no memory effects. Applying either operation followed +by the other is an identity. Ordinary assignments between integer and +floating-point types still perform numeric conversion; floating-point +arithmetic may change a NaN representation. + +These functions introduce compiler intrinsics: ordinary C bindings with reserved +external symbols, fixed signatures, and known meanings. The compiler recognizes +the external function's identity, including aliases and imported bindings, and +can replace its calls with ideal IR nodes. It does not recognize the spelling of +a local variable or an unrelated Simple function with the same name. No new +expression syntax is needed. + +| External C symbol | Signature | Public alias | +| --- | --- | --- | +| `simple_f64_bits` | `{ f64 -> i64 }` | `sys.math.f64Bits` | +| `simple_f64_from_bits` | `{ i64 -> f64 }` | `sys.math.f64FromBits` | + +[`Intrinsic.java`](src/main/java/com/seaofnodes/simple/node/Intrinsic.java) owns the +reserved-symbol table, signatures, effect queries, inlining, and ideal nodes. +Call/CallEnd delegate to it. The cheap inliner checks intrinsics before requiring +a Simple body or Return edge. It validates the signature and actual arguments, +then replaces the complete control/memory/value state. For these pure operations, +control and memory pass through unchanged. + +Unknown indirect targets keep ordinary calls. The runtime's +[`simple_crt.c`](src/main/c/simple_crt.c) supplies C definitions using `memcpy` +to preserve representations without aliasing tricks. A replacement definition +must honor the same contract. Ordinary C functions remain opaque to the optimizer. + +The ideal nodes support constant folding, inverse cancellation, evaluation, and +serialization. Floating-point constant interning and serialization retain raw +NaN bits. x86 emits `MOVQ` between XMM and integer registers; ARM emits `FMOV`, +and RISC-V emits `FMV.X.D` / `FMV.D.X`. Register allocation may add copies or +spills, and normal module-initialization checks still apply. + +Future intrinsics such as compare-and-swap or fences must define their memory +and escape effects explicitly, using nodes with the required ordering +dependencies. They must not inherit the pure conversions' passthrough memory +behavior. Atomic operations and hardware square root are not introduced here. + +`make test CLASS=IntrinsicTest` checks representation preservation, folding, +type errors, side effects, indirect C fallback, binary imports, and instruction +selection on all three backends, including emulation and native x86 execution. Simple also now recognizes hexadecimal (`0xff0000`) and leading-zero octal (`025755`) integer literals. @@ -163,15 +258,28 @@ Simple also now recognizes hexadecimal (`0xff0000`) and leading-zero octal represent more than 255 distinct memory regions. - Floating-point constants and register copies preserve raw NaN bits. +## Further reading + +The [grammar and code map](docs/31-grammar.md) is this chapter's language +reference. Runnable programs and their controls are in the +[examples](docs/examples/README.md). Library API references live beside their +implementations: [drawing](src/main/smp/sys/draw/README.md), +[windows](src/main/smp/sys/gfx.md), [audio](src/main/smp/sys/audio.md), and +[time](src/main/smp/sys/time/README.md). + +For inherited compiler behavior, start with [escape analysis in Chapter 27](../chapter27/README.md) +and [construction and partial references in Chapter 29](../chapter29/README.md). +Chapter 29 also links the detailed construction and escape implementation notes. + ## Build and run From the `chapter31` directory: ```sh -make libs CTAGS= # Download dependencies once. -make run-graphical-tictactoe CTAGS= -make run-clock CTAGS= -make run-breakout CTAGS= +make libs # Download dependencies once. +make run-graphical-tictactoe +make run-clock +make run-breakout ``` Dependencies stay cached across `make clean`. The run targets build the needed @@ -181,5 +289,5 @@ window and audio backends. Use `graphical-tictactoe`, `clock-example`, or Run the ordinary tests without a display or audio device: ```sh -make tests_nographics CTAGS= +make tests_nographics ``` diff --git a/chapter31/docs/31-grammar.ja.md b/chapter31/docs/31-grammar.ja.md index f4635f21..eca363c1 100644 --- a/chapter31/docs/31-grammar.ja.md +++ b/chapter31/docs/31-grammar.ja.md @@ -47,7 +47,7 @@ constructorParameterList : (constructorParameter ','?)+ ; constructorParameter : type '^'? bindingModifier? IDENTIFIER ; // ^ accepts an unfinished struct reference; ? independently permits null. // Only self may be read while incomplete; ^ arguments may be stored/forwarded. -// A new result is incomplete iff an actual argument is. See construction-groups.md. +// A new result is incomplete iff an actual argument is. See ../../chapter29/README.md#incomplete-types. // A method is an ordinary fixed function binding in a struct definition. // The compiler supplies self; it is not written in parameterList. @@ -82,7 +82,7 @@ primitiveType assignment : expression (assignmentOperator assignment)? ; assignmentOperator - : '=' | '+=' | '-=' | '*=' | '/=' | '&=' | '|=' | '^=' + : '=' | '+=' | '-=' | '*=' | '/=' | '%=' | '&=' | '|=' | '^=' | '<<=' | '>>=' | '>>>=' ; @@ -113,7 +113,7 @@ additiveExpression ; multiplicativeExpression - : unaryExpression (('*' | '/') unaryExpression)* + : unaryExpression (('*' | '/' | '%') unaryExpression)* ; unaryExpression diff --git a/chapter31/docs/31-grammar.md b/chapter31/docs/31-grammar.md index f4ca76f1..37300c46 100644 --- a/chapter31/docs/31-grammar.md +++ b/chapter31/docs/31-grammar.md @@ -64,7 +64,7 @@ constructorParameterList : (constructorParameter ','?)+ ; constructorParameter : type '^'? bindingModifier? IDENTIFIER ; // ^ accepts an unfinished struct reference; ? independently permits null. // Only self may be read while incomplete; ^ arguments may be stored/forwarded. -// A new result is incomplete iff an actual argument is. See construction-groups.md. +// A new result is incomplete iff an actual argument is. See ../../chapter29/README.md#incomplete-types. // A method is an ordinary fixed function binding in a struct definition. // The compiler supplies self; it is not written in parameterList. @@ -102,7 +102,7 @@ primitiveType assignment : expression (assignmentOperator assignment)? ; assignmentOperator - : '=' | '+=' | '-=' | '*=' | '/=' | '&=' | '|=' | '^=' + : '=' | '+=' | '-=' | '*=' | '/=' | '%=' | '&=' | '|=' | '^=' | '<<=' | '>>=' | '>>>=' ; @@ -133,7 +133,7 @@ additiveExpression ; multiplicativeExpression - : unaryExpression (('*' | '/') unaryExpression)* + : unaryExpression (('*' | '/' | '%') unaryExpression)* ; unaryExpression diff --git a/chapter31/docs/audio.md b/chapter31/docs/audio.md deleted file mode 100644 index 30817012..00000000 --- a/chapter31/docs/audio.md +++ /dev/null @@ -1,62 +0,0 @@ -# Optional background audio - -`sys.audio` uses [miniaudio](https://github.com/mackron/miniaudio) through an -optional native C backend. Playback runs on its own thread; the game keeps -processing input and drawing. No Python, CMake, codec packages, or sound files -are needed. Default builds/tests never download miniaudio or open a device. - -From `chapter31`: - -```sh -make libs CTAGS= # Once while online, or use make init. -make audio CTAGS= -make run-graphical-tictactoe CTAGS= -``` - -The last command builds both optional backends and runs the game. Accepted -moves get a quiet 70ms sine boop. A player win gets a 480ms rising C-E-G -celebration; a CPU win reverses the notes. Invalid input and occupied squares -are silent. Replay stops any previous cue. Win/loss cues replace the ordinary -move boop; draws use the ordinary boop. - -For direct execution in PowerShell, alongside `SIMPLE_MINIFB`: - -```powershell -$env:SIMPLE_MINIAUDIO = (Resolve-Path build/release/x86_64_v2_win64/simple_miniaudio.dll).Path -.\build\examples\x86_64_v2_win64\TicTacToeGraphical.exe -``` - -Linux uses `libsimple_miniaudio.so` in the corresponding release directory. -`SIMPLE_MINIAUDIO` must name the full backend path. Unset it or set it to `off` -for silent play. An unavailable audio device returns `ERROR` and the game -continues. Audio and graphics can be configured independently. - -| Operation | Meaning | -| --- | --- | -| `open()` | Open output and generate built-in sounds; `OK` (0) or `ERROR` (-1). Repeated open is safe. | -| `boop()`, `win()`, `lose()` | Play a built-in cue; same as `play(BOOP/WIN/LOSE)`. | -| `load(samples)` | Copy `i16[~]` mono PCM at `RATE` (48000Hz); return handle or `ERROR`. | -| `play(handle)` | Start/restart, replacing the current sound. Return `OK` or `ERROR`. | -| `stop()` | Stop playback; safe before open/after close. | -| `playing()` | Whether samples remain to submit; final device buffering may remain. | -| `close()` | Join the audio thread and free device/buffers; safe to repeat. | - -All calls belong on the main/game thread. Load custom sounds at startup: -there are 28 custom slots, each up to ten seconds, retained until close. -Custom handles must be reloaded after close/reopen. Signed samples range -from -32768 to 32767; quiet effects should use much smaller amplitudes. -Native code copies the array and never retains a Simple heap pointer or calls -Simple from the audio thread. Playback itself neither allocates nor waits for -the sound duration. This first interface plays one sound at a time. - -`audio.mk` pins miniaudio 0.11.23, cached under `lib/miniaudio-0.11.23/` by -`make libs` (or `init`; `lib` remains a setup alias). Only these explicit setup -targets can download dependencies. All builds, runs, and tests use local -copies, surviving `make clean`; missing cache entries fail promptly with setup -instructions. Windows uses the existing MinGW-w64 compiler; -Linux uses GCC and system pthread/math/dl libraries. No audio development -headers need installing. The upstream header includes its public-domain and -MIT-0 license options, copied beside the backend as `miniaudio-LICENSE`. -`make test-audio CTAGS=` builds the backend checks from the local cache -and runs a real audio thread with miniaudio's silent null -device; normal tests exercise the loader and game without hardware. diff --git a/chapter31/docs/construction-groups.md b/chapter31/docs/construction-groups.md deleted file mode 100644 index 197a6082..00000000 --- a/chapter31/docs/construction-groups.md +++ /dev/null @@ -1,241 +0,0 @@ -# Construction: field types and incomplete references - -Instance constructors use ordinary field Loads and Stores. There are two checks: -whether a field has a value, and whether an object reference is usable outside -construction. Neither requires a collection of constructor-group identities. - -## Field initialization - -New produces private `TypeMem` containing the object's `TypeStruct`, with -`TypeScalar.BOT` for fresh fields. Defaults emit ordinary Stores: zero for an -ordinary integer, null for a nullable pointer, no Store for a required field. -An assignment strongly updates its field in private memory. Phi meets the -incoming memories; a missing live arm survives because `BOT.meet(7) == BOT`. -An initialized unknown integer has `TypeInteger.BOT`, not `TypeScalar.BOT`. -Arrays retain their language-level zero filling. - -One `#selfMem` binding carries this memory through scopes and returns. A Load -checks its incoming field type. Constructor completion checks the merged Return -memory; the explicit constructor receives the declaration initializer's merged -result, including early exits. There is no backwards initialization query, -per-field parser state, or store-all instance exit. - -The existing Iter/Opto passes propagate these types; TypeCheck reports errors. -There is no extra construction type solve or retained source-use list. An -initialized field carried unchanged around a loop needs the optimistic SCCP -solution. Numeric fields in loop memory widen as scalar loop values do. -Arithmetic, conversions, and numeric Stores preserve Scalar.BOT, so a live bad -read cannot disappear merely because it is multiplied by zero. Genuinely unused -reads may be removed by DCE. - -The allocator's ConstructNode retains the constructor's final private memory -for its completion check. TypeCheck gathers these nodes during its existing -error walk and removes checked boundaries before lowering. The pass removal -exposes known failures; see [the late-check notes](deferred-construction.md). - -Internal construction memory parameters use actual allocation/initializer call -edges; the hypothetical external caller does not supply their memory. They -retain their memory family when there are no live callers. Function-valued -fields retain their declared signatures in private summaries, avoiding repeated -unfolding of a constructor whose returned memory contains its own function field. -Class singleton initialization keeps its older store-at-exit implementation. - -## Partial references and readable fields - -`self` and incoming `C ^arg` parameters are incomplete references. `C? ^arg` -also accepts null. Ordinary functions and constructors accept the qualifier on -struct parameters; arrays cannot be qualified this way. - -- An allocation result is incomplete if any actual argument is incomplete. -- With only completed arguments, including null, the result is complete. -- An incomplete reference may be stored into self or passed to a `^` parameter. -- Ordinary calls and stores into other objects require completed references. -- A borrowed partial can read fields its incoming type proves initialized. - It cannot write fields, even non-finals. Exact local aliases of self retain - the original constructor's access to its current private memory. -- An object-reference field read through a partial is conservatively - incomplete, with no initialized-field guarantees for its referent. There is - no inference of initialized-field requirements on `^` arguments. - Arrays are already initialized and cannot receive - incomplete elements, so an initialized array field can be used normally. - -For example: - -```simple -struct Child { - Test.Parent? parent; - new Child = { Test.Parent? ^par -> parent = par; }; -}; -struct Parent { - Child child; - int~ payload; - new Parent = { int n -> - child = new Child(self); // Incomplete result: self is incomplete. - // Retention does not authorize reading parent.payload through child. - payload = n; - }; -}; -val parent = new Parent(arg); -val local = new Child(parent); // Complete argument, complete result. -return local.parent==parent; // Lookup is allowed. -``` - -Here `Test` names the source unit. After the root Parent constructor completes, -the entire cycle is usable: all members have initialized their own fields, and -none could expose an incomplete reference to ordinary code during construction. -The Child constructor still treats its `^par` as incomplete when the actual -argument is complete. This public constructor also has unknown callers, whose -partial arguments promise no initialized fields, so `par.payload` is unreadable. - -## Forward field views - -At a use of self, `InitViewNode` combines the pointer with that program point's -private memory. Its TypeMemPtr contains declared types for initialized fields -and Scalar.BOT for missing fields. The node retains the declaration separately -from the incoming flow shape, so an exact self alias captured before a Store -can receive a fresh view afterward. Earlier calls retain their earlier views. - -For example, a private helper can read `x` while `y` is still unset: - -```simple -struct _C { - int~ x; - int~ y; - new _C = { int n -> x=n; y=_read(self); }; -}; -val _read = { _C ^p -> return p.x; }; -return new _C(arg).y; -``` - -Parm meets the incoming shapes using the normal type flow. If any live caller -lacks `x`, Scalar.BOT survives and the Load reports the missing initialization. -Unknown callers supply an empty field promise. Parsing must also start borrowed -parameters at that bound: otherwise early folding of `p.x*0` could hide a bad -read before SCCP. The hidden constructor receiver retains its declaration; -its private memory supplies its read checks and precise field updates. - -Values still come from normal memory. Before a call borrowing self, EscapeNode -borrow slices carry the current constructor Stores onto the ordinary call -memory edge. These slices are aliasable and do not publish the private identity -or its fields into the global escape sets. No hidden partial-memory arguments, -field bitsets, additional passes, or recursive flow queries are introduced. - -InitView folds before TypeCheck when its input already has the same type and -retains a structural partial view. Nested partial-only Construct wrappers also -collapse. A Parm's current partial type alone is insufficient: inlining may -later substitute a complete actual argument, which must not grant the borrowed -parameter permission to write or publish that object. The completion form of -Construct already folds once its memory proves initialization and its result -type matches its input. - -TypeCheck checks the consumers and erases remaining InitViews along with the -checked Construct boundaries in its existing walk. A surviving field view is -not necessarily erroneous: a reader may need only the initialized subset. -Construct remains necessary for -final-field completion and for the partial qualifier of each source `new`. -Alias Phis and nested reference loads are conservative; they do not acquire -the original constructor's write permission. This prototype adds no general -ban on overlapping allocations of the same class: only the owning receiver -uses private memory, while borrowed reads use aliasable memory. - -## Aliases and loops - -Incomplete is a property of a value, not just the current contents of a parser -Var. Consider `while (n--) { use(p); p = self; }`: the backedge introduces an -incomplete value after `use(p)` has been parsed. `TypeMemPtr._partial` carries -that restriction through ordinary forward typing. It is an independent -two-point lattice: meet ORs the restriction and dual complements it. Copies, -conversions, Stores, and Phis preserve it; a merge is incomplete if any live -input is incomplete. A `^` formal stays incomplete even when its known callers -are complete. The receiver's private memory identifies the own-self exception; -another incomplete pointer of the same class has no such permission. - -A small `ConstructNode` wraps each source `new`. Its runtime value is the -allocator result; its type adds the OR of that call's actual argument qualifiers. -This distinguishes `new Child(self)` from `new Child(null)` even when both call -the same constructor. Looking only at the shared callee Return would lose this -distinction. The node disappears after TypeCheck, before lowering. - -A completed receiver gives a completed view of its pointer fields. Construction -may retain incomplete references but cannot publish them, so reaching the root -`new` boundary with complete arguments makes the entire reachable cycle usable. -There is no group identity or traversal to mark members complete. Conversely, -object-reference fields read through incomplete self remain conservative, even -if the particular stored reference was complete. - -The existing optimistic SCCP solve also handles qualifier cycles. For -`p = null; while (n--) p = new Link(p);`, no input introduces incompleteness, -so `p` stays complete and a subsequent field read is allowed. A backedge carrying -self instead makes the Phi and its uses incomplete. - -`Construction` selects private self memory during parsing; it retains no -source-use lists or flow facts and performs no recursive Load/Phi/Call query. The old -root and allocation bitsets are gone. There are no field-requirement sets, -hidden `^` memory arguments, or runtime group objects. - -`PartialReadTest` exercises field reads, missing fields, forwarding, merged -callers, loops, exact aliases, constructor retention, and borrowed write and -publication restrictions. `ConstructionGroupTest` exercises cycles, complete/null arguments, prohibited -lookups/publication, aliases, branch merges, complete and incomplete loop -backedges, and declared restrictions with only complete callers, including an -uninlined constructor through machine encoding. `ConstructorCompletionTest`, -`FinalConstructionTest`, and `BoundaryTest` exercise field-memory semantics. -The former inferred-requirement litmus tests are preserved, explicitly deferred, -in `ConstructionRequirementsTest`. Separate compilation of `^` functions is -still deliberately unsupported. The pointer qualifier has an object-file -representation, but importing and checking the full construction contract is -outside this experiment. Rebuild chapter 29 object files after the type-format -change. - -## Deferred field-aware contracts (2026-11-07) - -Decision: do not implement inferred contracts now. Cliff considers the required -infrastructure too large for the feature alone; revisit when a general -backwards/liveness flow is justified, potentially for memory management. -The later forward-field-view prototype above does not implement this contract -discovery proposal. Separate compilation of `^` interfaces remains rejected. - -The intended extension would let functions and constructors receive partially -initialized objects, read initialized fields, retain partial references with -their restrictions, and write non-final fields. Only the original constructor -would retain permission to initialize/reassign its own final fields; passing a -pointer must not pass that permission. Final-field reads during construction -would not establish value stability against later writes by that constructor. - -The proposed contract representation uses normal types, not a separate field -bitset. For a function reading only `P.pi`, its unknown-caller default would be -schematically `Partial{pi:declared-pi-type, name:TypeScalar.BOT}`. Scalar.BOT -means no initialization guarantee, not a requirement that the caller leave the -field unset. Required fields receive their declared types, covering every legal -external caller. MEET with actual arguments preserves those guarantees only -when the callers satisfy them; extra initialized fields supplied by locals do -not strengthen the body beyond the external contract. TypeStruct/Field already -meet field contents, and nested/cyclic types can represent nested contracts. -TOP is not the missing-initialization marker. - -Cliff proposed discovering conservative, context-insensitive requirements after -Iter and before SCCP. Freeze the resulting default argument types on functions; -SCCP consumes them without refining the contracts. Reads on branches SCCP later -eliminates may still impose requirements, as may reads following assignments. -That rejection of some valid programs is acceptable for an opt-in `^` feature. -Combine compatible requirement shapes with JOIN; combine possible caller states -with MEET. Keep the contract distinct from the merged Parm type, and check each -actual argument against it for a call-site diagnostic such as -"foo requires Partial.pi to be initialized". Serialize contracts with declaration -metadata so checking imported calls does not require loading bodies. - -The complication is discovering and propagating those contracts. Local SSA -aliases share values; Phi demands reach every input. A demand on a loaded field -becomes a nested receiver requirement. Calls substitute actual arguments for -formals, and recursive forwarding needs a convergent propagation rule. Cyclic -types represent recursive requirements but do not by themselves prevent a -discovery algorithm from unfolding progressively deeper paths. Indirect calls -need contracts available through their callable interfaces; returns need usable -guarantees without retroactively strengthening an exported contract for a client. -Stored references and helper writes also require a coherent account of private -construction memory and object identity; that discussion was deliberately left -unfinished. None of this requires H-M or bidirectional type inference, but it -does require a substantial backwards demand analysis to handle well. - -The ignored ConstructionRequirementsTest retains useful litmus cases, not an -approved implementation plan. Do not restart this work without a new request. diff --git a/chapter31/docs/deferred-construction.md b/chapter31/docs/deferred-construction.md deleted file mode 100644 index 104ab9e9..00000000 --- a/chapter31/docs/deferred-construction.md +++ /dev/null @@ -1,385 +0,0 @@ -# Deferring construction checks: experiment - -The [escape-flow continuation](escape-flow.md) supersedes the frozen-public -fallback and remaining recursive-test failures described later in these notes. -All four recursive examples now pass their original printed-IR expectations. -The older audit below records the evidence that led to this change. - -The extra construction pass is removed from the working implementation. -`Construction.check()`, its retained source-use lists, `Iter.types()`, and the -separate constructor-Return walk are gone. Errors now belong to the existing -TypeCheck walk; ConstructNode retains final private memory for completion checks. -No additional whole-graph pass was added. Constructor rejection tests remain active. - -## Constant folding - -`TypeScalar.BOT` is not an initialized integer. Arithmetic, comparisons, -negation, numeric conversions, and typed Stores must preserve it rather than -manufacturing an integer or floating-point result. In particular, `x*0` and -`x==x` cannot become constants while `x` has this type. An initialized unknown -integer still permits those folds. - -The scan found and changed these related cases: - -- Multiplication by zero now folds in `compute`, after checking numeric inputs. - Integer strength reduction also waits for integer operands; an unfinished - loop Phi could eventually become a float. -- Same-input comparisons fold in `compute`. Floating comparisons keep NaN - semantics; `x==x` is not necessarily true. The integer range implementation - of `!=` also had the equality answers reversed. -- Arithmetic pushed through Phis uses each copied operation's `compute`, - including floating-point constants, instead of an unchecked integer cast. -- Known array length offsets and element shifts fold in - `ConFldOffNode.compute`, rather than its `idealize`. -- `Not`, unary minus, conversions, and Stores preserve unknown initialization. - `RoundF32` already passed that type through. - -This does not ban creating constant *operands* in rewrites such as `x*8` to -`x<<3`. Memory forwarding still has cases that return a stored constant or an -array's zero-filled element; these were inspected but not rewritten into a new -memory analysis. `Load.idealize` retains a `Scalar.BOT` load. - -The changes exposed a rejected-Phi-fold worklist cycle. Factoring -`Phi(bool & 7, integer & bool)` widens the result from `bool` to `[0-7]` and -must fail. Building and then killing the candidate woke the same dependencies -forever. The trial now computes its types before registering use edges. - -## Preserving the constructor body through optimization - -This regression must reject a live incomplete lookup: - -```simple -struct Child { - Test.Parent? parent; - new Child = { Test.Parent? ^par -> parent = par; }; -}; -struct Parent { - Child child; - int~ payload; - new Parent = { -> - child = new Child(self); - payload = child.parent == null; - }; -}; -return new Parent().payload; -``` - -`child` is incomplete because its constructor received incomplete `self`. -Reading `child.parent` must therefore fail. The read supplies the final result; -this is not a discarded local or dead-code issue. - -The decisive failure was private-memory Parm typing. During Iter, inlining -removed a real caller while the function still had its unknown-caller edge. -The special case returned MemTop anyway. That erased the memory merge, Store, -and the bad Load feeding it, before TypeCheck could report the error. - -Parms now use their normal merge. Hidden initializer/constructor helpers have -only actual allocator callers; the source-visible constructor binding denotes -the allocator. Public allocators still receive unknown callers, so unused public -constructor bodies remain checked. This also avoids poisoning a helper's private -memory with a fictitious external default. - -Inlining presents a second issue: a complete actual pointer must not grant -permission to read a restricted formal. A partial-only ConstructNode gives -self and ^ parameters their body view independently of Parm typing. It remains -until TypeCheck. Load's alias search recognizes that this view preserves the -address, while compute/err continue to see the qualified pointer. - -A smaller regression reads an unwritten field through a self cycle: - -```simple -struct C { - C next = self; - int~ x; - new C = { -> x = next.x; }; -}; -return new C().x; -``` - -Both examples now reject at TypeCheck. A positive regression initializes x to -7, increments it in the constructor, and checks that the result folds to 8. - -The broader run exposed a function-lifetime bug during SCCP: unlinking calls -could delete a body subsequently rediscovered from a type-level function -reference. Returns are kept during the existing reset walk and released once -call edges have been rebuilt. No additional graph walk is needed. - -Class-init dependency discovery also skips a CLInit whose receiver has not -resolved to a class. A Scalar.BOT receiver is left for its Load's TypeCheck -error, rather than dereferencing a null class name. - -The trial successfully uses the existing passes to prove a chain built from -`null` complete. It also rejects direct `par.payload`, `par.payload*0`, and -`int x = par.payload; value = x*0` after the arithmetic/conversion repairs. - -Genuinely unused reads are allowed to disappear under late-check semantics. -Rejection tests must keep the read live. `testUnusedIncompleteReadCanDie` checks -that an unused `par.payload` read is eliminated and the program returns 5. - -## Optimization differences and register allocation - -`Chapter18Test.testFcn9` exposed an independent escape bug. StopCU treated the -class initializer's synthetic self as an object already held by an external -caller. Its broad function-valued field type exposed the local x function even -though the initializer never returned and x had no callers after inlining. -Skipping that synthetic argument restores the empty escape set for x and the -expected `return Top;`. Actual public-call arguments still escape normally. - -That correction exposed `Chapter18Test.testFcn8`: a Store computed from TOP -memory interpreted its optimistic singleton bit as established private memory. -It widened a function value to the declared signature, then narrowed its FIDX -set when memory resolved. Store now returns TOP while its memory is TOP, so -SCCP remains monotone. - -The String differences have a different cause. In Chapter19, the private -_hashCodeString body dies; the surviving functions are the initializer, -allocator, equals, and public hashCode. Its golden string now omits the two dead -private-helper MemTop Returns and matches the current addition order. -`Add.spine_cmp` breaks this tie by node ID. Strength reduction creates the Sub -in IterPostOpto, after the byte Load (Sub#594 versus Load#504 in one traced copy), -so the Sub sorts to the left. This is node ordering, not a lost value type. - -In the Chapter20/21 fixtures, _hashCodeString really escapes through the implicit -return, and hashCode contains an inlined copy. Before the allocator repair, both loops needed an extra x86 -register copy with the new addition operand order. A disposable probe -swapped only `((hash<<5)-hash) + byte` to `byte + ((hash<<5)-hash)` after Unlink: -no types or live functions changed, but the weighted split score fell from 37 -to 21. Each hash body fell from 17 to 9; the allocator stayed at 3. - -Reconstructing the earlier source by reversing the saved construction-pass -removal patch reproduces the expected 29. Its standalone _hashCodeString costs -17, inlined hashCode costs 9, and allocator costs 3. Before the allocator repair, -these costs were 17, 17, and 3. Both versions contain two hash loops; no inlining decision changed. -Current code emits two fewer functions, the dead initializer/constructor helpers, -which contributed zero. Thus the entire increase is one loop-weighted register -copy in the inlined hashCode body, not another retained function or stack spill. - -With the old operand order, the byte Load can write the loop's hash register -and Add accumulates the shifted/subtracted value into it. With the new order, -Add's destructive input is the Sub result. Its two-address tie plus the Phi -backedge joins the shift/Sub/Add chain to the old hash live range, which overlaps -the shifted value at the subtraction. `RegAlloc.splitSelfConflict` inserts a -`use/self/two` copy before Add. The existing commute heuristic in `splitByLoop` -is not reached: self conflicts take an earlier splitting path. Commuting Add -before splitting is the concrete optimization opportunity. - -The allocator now does this in `splitSelfConflict`, using the existing failed- -range traversal and scratch list. It commutes two-address operators when the -RHS has one use and belongs to a different live range, then omits the copy for -the tie it broke. An allocator-generated Split is excluded: its single use can -hide a longer-lived value, and commuting onto it can undo an earlier repair. -The existing coloring retry rebuilds live ranges. There is no new whole-IR pass -or analysis structure. The machine's `commutes()` hook covers Add, Mul, Xor, -And, and Or (and commutative floating instructions). - -The String score is now 21: each hash body costs 9 and the allocator costs 3. -The three x86 expectations are updated to 21. A single regression exercises -all five integer operators in both machine operand orders, checks register -constraints, and encodes the results. Existing testFlags2 guards against the -Split-operand regression. - -## Incremental Iter setup - -Iter no longer resets and requeues the whole graph after parsing. `Node.init()` -queues initialized nodes, and Calls queue themselves so Iter can link targets -loaded after the call was parsed. Iter seeds its new global escape summary, -then drains the worklist. Import loading still resets the newly loaded nodes -and repairs affected neighbors. - -Removing the sweep also exposed an unused receiver left behind when field -lookup switches from an instance to its class. That path now releases the keep -and kills the receiver if unused. - -FldOffNode's base is data in slot 1. Slot 0 is reserved for control; putting a -data parameter there made inliner body discovery exclude an unresolved offset. -The regression `CallEndTest.testUnresolvedOffsetInInlineBody` checks that the -offset belongs to the function body even before its type resolves. - -## Type upgrades in Opto setup - -ParseAll still closes the named types and freezes the public interface after -loading all units. It no longer walks the IR. Opto installs those closed types -and resolves forward references during its existing reset walk. Setup runs no -peepholes against the partly reset graph: resolved FRefs propagate their input -type in SCCP and disappear during subsequent peepholes. Construction identities -also wait until this setup has installed complete field declarations. - -That walk retains Returns while call edges are rebuilt, gathers unresolved -numeric modes, and records dependencies for cleanup after SCCP. Type upgrades -also register cleanup dependencies, even if the eventual value type is unchanged. -Old Iter types are snapshots for change detection, not upper bounds after -recursive declarations have been closed. SCCP still asserts monotone falling -types and a complete worklist within its own solve. - -The move exposed assumptions formerly hidden by early upgrades. Resolving an -already known class name must retain its known fields instead of replacing them -with an empty placeholder. A Load must not forward a stored pointer whose open -shape is weaker than the Load's computed type. Escape must retain escapes from -the actual private value before narrowing it to its declared field type, so -selecting a Store out of a MemMerge does not introduce new escapes. - -An unknown return or memory effect carries FULL escape sets. StopCU and -GlobalEscape preserve that bound: narrowing it to public names would omit -private objects and callbacks that a subsequent load-forwarding rewrite can -reveal. Both summaries recompute from their inputs without retaining previous -escape sets. Refining a value removes possibilities; it never adds escapes -outside the old bound. IterPeeps has no special summary handling, and its -worklist assertion requires every node's type to lift, including queued nodes. -`testUnknownEscapesRefineToPrivateValues` checks both escape sinks; -`testPrivateRecursiveReturn` covers cyclic private objects and field loads. - -The ordinary dependency mechanism also covers signature refinement and lazy -imports. FunNode depends on its Return when refining its signature. Calls -depend on their target FunNode; while a target is absent, they depend on Start -and retry when a linker mapping is installed. Loading bodies and adding call -edges still use `Iter.repair` for graph changes, not for value refinement. - -SCCP's Start linking honors FULL for private targets too. Incoming arguments -are not themselves outgoing escapes; Stores, Returns, and external-call -arguments describe those effects. Constant singleton field slices carry the -stored value's escapes, not unrelated bulk-memory escapes frozen at the time -of folding. This preserves precision for local recursive callbacks. - -As bounds sharpen after SCCP, FunNode removes unknown callers even if concrete -callers remain. Called initializers retain their Return through StopCU because -CLInit has no Return edge. Removing an uncalled function queues the affected -Stops, and compilation-unit wrappers retain distinct identities even when -empty. These are worklist notifications and ownership rules, not extra passes. - -### Remaining precision issue with FULL escapes - -The monotone bounds expose a feedback problem in the existing grand cycle. -In `Chapter12Test.testPrivateRecursiveReturn`, SCCP sees BOTTOM for the final -load chain and therefore FULL escapes. These feed through Start's memory into -the function memory results. Post-SCCP forwarding resolves the return to `_B`, -but that memory cycle remains at MemBot and keeps private constructors callable -by unknown callers. This is conservative, but loses the previous dead-function -elimination. It does not justify narrowing BOTTOM to public names or adding -the IterPeeps widening repair back. - -For this example, the root Return goes from `[Ctrl, MemBot, Bot]` after Opto to -`[Ctrl, MemBot, *_B]` after TypeCheck; Stop's memory remains MemBot. The remaining -design question is how to avoid this feedback while retaining conservative -bounds and the existing pass budget. The current experiment leaves the printed -IR expectations unchanged so they continue to expose this loss of precision. - -The source-validity audit separates these cases from Chapter10 `testIfOrNull`. -That test originally returned the nullable pointer itself. A historical edit -changed it to `return bar.a;` without adding TypeCheck, leaving a real null -error hidden behind a printed-IR assertion. It now again returns `bar`, runs -through TypeCheck, and passes with `return Phi(Region,null,Test._Bar);`. - -All four remaining programs pass TypeCheck. The Chapter12 recursive-object -tests have one pending bad Load after Opto; forwarding eliminates every Load -and resolves the result to `17`, `_B`, or `_R`, while escape memory stays MemBot. - -The two Chapter17b forward-type tests now pass their original IR expectations -and explicitly run TypeCheck. Their undeclared `B` is an opaque external type, -not an arbitrary unknown local value. EscapeNode uses the frozen public -interface as its fallback for that type, preserving escapes already present -in its private and public memory inputs. This applies to both the actual private -value and the declared field bound: in `testForward1`, the private array element -type is already `B?`. Bounding only FIDXs is insufficient; FULL aliases expose -private class fields, which then expose their constructor FIDXs. - -CodeGen caches the fallback when ParseAll freezes the public interface. It -returns FULL until Opto's existing reset walk installs the closed types into -the IR. Only then does an open `_fref` reliably denote an external object. -Ordinary open local structs, `TypeScalar.BOT`, and abstract pointers still -require FULL. No new pass or IterPeeps hook is involved. - -### Escape-bound audit - -All Chapter29 `escapesFrom`, `XInt.FULL`, and `TypeMem.BOT` uses were reviewed, -including the equivalent `escapes` helper and indirect `makePrivate` uses. -The following remaining sites warrant work; they have not been narrowed here: - -* **StoreNode's three `escapesFrom(val)` paths.** The singleton constant, - private instance, and ordinary aliasing paths still treat an opaque external - value as FULL. A concrete example is: - - ```simple - struct _A { B? !b; new _A = { B? p -> b=p; }; }; - val wrap = { B? b -> return new _A(b); }; - return wrap; - ``` - - This passes TypeCheck, but the surviving Stores of `b` have FULL FIDX and - alias sets and keep an extra `_A` allocator. Do not mechanically substitute - the public default: singleton slices deliberately discard unrelated incoming - memory escapes. A narrower opaque bound must retain private values previously - given to external code, without freezing unrelated transient escapes into - singleton constants. Ordinary aliasing Stores already retain incoming sets. - -* **StopCU return values, CallNode external arguments, and SummaryNode arguments.** - These use `escapes`, which currently duplicates the unbounded `escapesFrom`. - `val identity = { B? b -> return b; }; return identity;` passes TypeCheck but - gives StopCU MemBot. Likewise, - `val send = { B? b -> { B? -> int } retain = "C"; return retain(b); }; return send;` - gives the native CallEnd MemBot. These are concrete instances of the same - opaque-type precision loss. A future change can share the bounded helper, - while retaining incoming/returned memory, explicit private arguments, and - imported-summary effects. StopCU's public function seed and `escapesAliases` - class seed describe known declarations; GlobalEscape's `escapes` calls merely - union already computed TypeMem sets. - -* **CLInitNode's possible-initialization result.** Even a known initializer - yields TypeMem.BOT until its ready flag is true; only the initialized flag's - slice is precise. This loses both memory-content and escape precision. - CLInit has an analysis call edge but no Return edge supplying callee effects. - Improving it needs a dependency on the initializer's effects, including - recursive dependencies. The public interface alone is not a safe cap: that - initializer can publish private callbacks. Its unresolved-flag BOT fallback - is also conservative, but normally disappears when the receiver resolves. - -* **CallEndNode's unknown or unlinked target result.** Both return TypeMem.BOT. - The unlinked case covers invalid calls and transient missing edges; SCCP links - valid finite targets before computing CallEnd. Truly unknown targets can be - local private functions as well as external functions, so a public-only cap - would be wrong. Native calls already use CallNode's argument/memory effects. - Any refinement must distinguish target provenance and retain explicit private - arguments; it is not the same small fix as an opaque external object. - -The other broad defaults appear justified: - -* TypeMem's generic BOTTOM/scalar/pointer cases and TypeStruct's unknown scalar - fields must include private callbacks that later value refinement can reveal. - Private-memory declarations/Phis use `makePrivate(BOTTOM)` for the same reason. - MemMerge's `makePrivate(struct)` describes actual fields, not an external - opaque object. -* Parser/function memory declarations, initial node types, TypeTuple.STATE, - and low-family error fallbacks in Store, MemMerge, BulkMemPhi, Start, and - TypeTuple need worst-case memory. CallNode and SummaryNode likewise cannot - promise bounded effects when their inputs are still arbitrary low values. -* Iter's import reset gives newly loaded nonconstant memory FULL before repairing - affected neighbors. Saved types belong to another caller context; constants - retain their own computed types. This is a safe pessimistic seed, though it - can contribute to the existing memory-cycle precision problem. -* TypeFunPtr's FULL signatures and TypeRPC.BOT describe unknown function/return - targets. Serialization/remapping preserves the FULL sentinel; type gathering - exercises it; LoopNode's `isa(TypeMem.BOT)` is a type-family check. These do - not independently manufacture an escape effect. - -Ignoring assertions, the remaining whole-node walks through TypeCheck are -Opto's setup/reset and TypeCheck's error scan. Class-init checking separately -scans function control flow and runs SCC over the resulting dependency graph. - -## Validation - -Chapter29's latest run tested 594 active cases with assertions: 590 passed and -four printed-IR comparisons failed. `make -k tests` ran raw0 (400/404), raw1 -(38), standalone (13), system (29), and fuzzer (1); the aggregate group (109) -was run separately because Make skips it after a prerequisite failure. -The remaining failures retain extra private constructors: Chapter12 `testCoRecur`, -`testCoRecur2`, `testCoRecur3`, and `testPrivateRecursiveReturn`. Both Chapter17b -forward tests pass unchanged goldens. TypeTest.testOpaqueExternalEscapes checks -both fallback sets, preservation of prior private escapes, and FULL for ordinary -unknowns. System, spill, import, callback, and constructor tests pass. The only -golden changed during the earlier source-validity audit belongs to the restored -`return bar;` source; none were changed to accept extra functions. - -The offset regression fails with the old slot-0 layout. Constructor and -boundary tests pass, including both missed rejections and the prior NPE. -Printed-IR expectations omit the dead private-helper MemTop Returns; no -rejection expectations were relaxed. The three String spill checks now expect -21 on x86, with the same live functions and inlining decisions. diff --git a/chapter31/docs/drawing.md b/chapter31/docs/drawing.md deleted file mode 100644 index b99c1bf8..00000000 --- a/chapter31/docs/drawing.md +++ /dev/null @@ -1,103 +0,0 @@ -# Drawing in Simple - -`sys.draw` draws into an ordinary `u32[]`. It has no native dependencies and -does not open a window. `sys.gfx` presents the resulting pixels using the -optional [MiniFB backend](graphics.md). - -```simple -val canvas = new sys.draw.Canvas(600,780); -u32 orange = 0xe47b57; -canvas.clear(sys.draw.WHITE); -canvas.fillRect(20,20,180,80,orange); -canvas.rect(20,20,180,80,3,sys.draw.BLACK); -canvas.circle(300,200,48,8,sys.draw.BLUE); -canvas.fillCircle(420,200,20,sys.draw.GREEN); -canvas.line(40,320,250,440,12,orange); -canvas.text(40,500,"YOUR TURN",4,sys.draw.BLACK); -// After sys.gfx.open succeeds: -sys.gfx.present(canvas.pixels); -``` - -## Small raster API - -Coordinates start at the upper left; x increases rightward and y downward. -Drawing methods return the canvas for chaining. Everything is opaque RGB; -there is no blending, antialiasing, transform stack, or native drawing state. -Coordinates accept `i64` so ordinary widened arithmetic can be passed directly. -Circle radii and circle stroke widths are `int`. Use screen-sized coordinates, -extents, and stroke widths. - -| Operation | Behavior | -| --- | --- | -| `rgb(r,g,b)` | Clamp components to 0–255 and pack RGB. `BLACK`, `WHITE`, `RED`, `GREEN`, and `BLUE` are available too. | -| `new Canvas(width,height)` | Allocate a zero-filled pixel array. Dimensions must be positive and their product must fit a signed 32-bit index; invalid sizes exit with status 1. Allocation can still fail for lack of memory. | -| `clear(color)` | Fill the entire canvas. | -| `pixel(x,y,color)` | Set one pixel; ignore points outside the canvas. | -| `fillRect(x,y,w,h,color)` | Fill a half-open rectangle: x through x+w-1, y through y+h-1. | -| `rect(x,y,w,h,thickness,color)` | Draw an inward outline. A sufficiently wide outline fills the rectangle. | -| `fillCircle(cx,cy,radius,color)` | Fill a circle; radius zero draws its center pixel. | -| `circle(cx,cy,radius,thickness,color)` | Draw an inward circular outline. | -| `line(x0,y0,x1,y1,thickness,color)` | Draw a round-ended segment. A zero-length segment draws a round dot. Thickness is its geometric diameter, sampled at integer pixel centers. | -| `text(x,y,string,scale,color)` | Draw a 3×5 bitmap font, with one column between characters. Upper/lowercase ASCII letters, digits, spaces, and basic punctuation are supported. Newline advances six scaled pixels. Unknown characters use `?`. | - -Shapes clip to the canvas. Nonpositive rectangle extents, stroke widths, or -text scale do nothing; negative circle radii do nothing. Line and circle -coverage scans only the clipped bounding box, which is sufficient for small -turn-based games. This is a starting raster library rather than a fast animated -renderer. The pixel array remains available for direct drawing and inspection. - -Packed colors use hexadecimal literals (`0xRRGGBB`); `rgb(r,g,b)` remains handy -for computed components. The font masks use leading-zero octal, with five -digits after the prefix: each digit is one three-pixel row, top to bottom. -For example, `A` is `025755`: rows `010`, `101`, `111`, `101`, `101`. -The font includes all printable ASCII punctuation except `@`, `&`, and `$`, -which use the question-mark fallback. Colons and slashes support clock and date -labels; quotes, brackets, arithmetic signs, and other small symbols fit in 3×5. - -## Button widget - -`new sys.draw.Button(x,y,width,height,label)` creates a rectangular software -button. It owns no window or native resources. Feed pointer coordinates and -the held mouse-button state to `update(x,y,down)` once per event-loop iteration. -It returns true once on release inside, provided the press began inside. -Dragging in from outside does not activate it; releasing outside cancels. - -`hovered` and `pressed` expose visual state. Set `enabled=false` to cancel a -pending press and disable activation; `label` can be changed at any time. -`contains(x,y)` uses half-open bounds. `draw(canvas,scale,foreground,background,active)` -paints the button and centers its 3x5 label when it fits. Colors belong to the -caller. Keyboard shortcuts belong to the application; this small widget has -no focus system. The [clock example](examples/Clock.smp) shows mouse activation -and a Space shortcut in the same single-threaded loop. - -## Graphical tic-tac-toe - -From `chapter31`: - -```sh -make run-graphical-tictactoe CTAGS= -``` - -Click an empty square or press **1–9**, numbered left-to-right, top-to-bottom. -You are X; the CPU is O. It wins when possible, blocks your immediate win, -then prefers the center, corners, and edges. The result stays visible with -the winning line highlighted. Press **R** or **Space** to start a new game, -or **Q**/**Escape** to quit. Restart is also available during a game. - -Held buttons and keys do not take repeated turns. Moving the pointer highlights -empty cells. The canvas is redrawn only after a move, restart, or hover change; -polling still processes window events and waits between polls. - -`make graphical-tictactoe CTAGS=` builds without opening a window or requiring -MiniFB. Its output is `build/examples/x86_64_v2_win64/TicTacToeGraphical.exe` -on Windows or `build/examples/x86_64_v2_SystemV/TicTacToeGraphical` on Linux. -Backend discovery and explicit overrides follow [the pixel-window instructions](graphics.md). -Passing any argument performs a five-poll, self-closing smoke test. - -The original `make tictactoe` still builds the terminal game. -The graphical game also uses optional [background audio](audio.md): a soft -boop for accepted moves, rising tones for a player win, and falling tones for -a CPU win. Bad input is silent. The run target builds/configures both backends. -`make test CLASS=DrawTest CTAGS=` checks raster pixels and complete game turns -without a display. `make tests_nographics CTAGS=` runs the ordinary suite with -the backend disabled. diff --git a/chapter31/docs/escape-flow.md b/chapter31/docs/escape-flow.md deleted file mode 100644 index 8ad49f15..00000000 --- a/chapter31/docs/escape-flow.md +++ /dev/null @@ -1,147 +0,0 @@ -# Outside-world escape flow - -The `escape-flow` branch developed this design in Chapter29 and backported it -to Chapters 28a/28b. Chapter28a uses `LocalIds` and its existing initializer -root/lowering protocol; Chapter28b adds saved summaries and cofinite identity -remapping. Neither port imports Chapter29's deferred-construction model. - -## The cycle - -The outside world's access to local objects and functions is a value in the -Start/Stop cycle. Public declarations are not that value. The frozen public -interface inventory has been removed; public-method and public-alias tests -check the converged outside escape sets directly. - -At Opto setup, the outer Start receives a constant foreign-identity seed: - -``` -foreign identities = FULL minus identities owned by this compilation -outside identities = foreign identities union discovered local escapes -``` - -Known native function and storage identities are foreign too. The infinite -tail permits future foreign functions even when no local callback has escaped. -The finite exclusions include registered imported identities, including bodies -represented by summaries. This scans identity tables, not the IR. Opto's -existing reset/worklist solve discovers the local escapes. - -StartCU includes the shared outside state. Infinite FIDX sets must retain their -exclusions: `Opto.linkStart` checks each local function's membership rather than -treating every cofinite set as FULL. Serialization remaps a cofinite set by -remapping its finite exclusions and complementing again. - -Before Opto, outside queries remain pessimistic. During SCCP, a consumer can -read the foreign seed before Start has run: otherwise a temporary finite set -can turn a generic foreign callback into an unrelated local function with the -same arity. No previous escape result is accumulated to repair value flow. - -## Consumers and dependencies - -* Memory and callback defaults for unknown callers use Start's memory - projection. Parm applies its declared callback signature to the escaping - FIDX set. Defaults whose values do not depend on escapes remain constants. -* Unknown/native CallEnd results use the outside state and the current call's - exposed arguments. Callback results are bounded by their declared signature - and the outside FIDX set. Explicit linked Return effects are retained. -* CallEnd registers a direct dependency on Start. Depending only on Call is - insufficient: Call can stay CONTROL while the outside set changes. This - first implementation uses `addDepForwards`; it does not change CallEnd's - input layout or introduce a synthetic Fun/Return pair. -* Infinite calls use the outside continuation. Escaped local functions remain - callable through Start, and their effects return through Stop. Attaching - every same-arity body to an infinite call is incorrect: argument/result - families may differ despite the equal arity. -* Outgoing Call argument exposure is independent of CallEnd, including a call - that never returns. The shared fixed point also permits immediate callback - round trips and reentrant calls. -* Opaque external values in Escape, Store, Return, and imported-summary paths - use the current outside/input-memory bound. Explicit private values and - already accumulated escapes remain included. Arbitrary local BOTTOM values - still require FULL. -* Function-valued Loads use their memory input's FIDX bound, joined with the - field declaration. They do not independently manufacture an escape set. - -CLInit was another unconditional producer of FULL. During Opto it now depends -on the known initializer's Return and merges those effects with incoming -memory. It waits for live memory before publishing effects. Lowering computes -the replacement CallEnd's linked type before exposing its projections, so a -temporary unlinked MemBot cannot widen the already analyzed caller. - -## Why the recursive tests needed local precision too - -All four former Chapter12 printed-IR failures pass their original expectations. -The problem was not solely an outside-call default: - -1. Convert widened a non-null pointer to a nullable declaration until its later - identity rewrite. It now preserves non-nullness in compute. Preserving the - entire source shape conditionally failed the existing monotonicity test; - shape and access still follow the declaration. -2. A Load could wait until post-SCCP Store forwarding to recover that non-null - pointer. In the meantime the next dereference produced BOTTOM, which fed - FULL around the memory cycle and revived private constructors. -3. Forwarded addresses, resolved field aliases, and already-bypassed CLInit - projections were also waiting for graph rewrites. - -Load's existing forwarding search now supplies pointer value facts during -compute, without constructing or rewriting nodes. It can recognize a stored -address through a valid pointer conversion or a proven forwarded Load, use a -resolved named field before layout, and follow an existing CLInit bypass. -The same dependency mechanism reruns the search when its evidence changes. -Nullable/incomplete access checks still precede this sharpening; arbitrary -memory Phis and unknown stores remain barriers. This adds local queries, not a -new whole-program pass, analysis map, or second IR. - -## Hidden class receivers - -A class function's hidden `#self` defaults to its owning class singleton. -Seeding that input with TypePtr.PTR used to give FULL escapes when forwarded -to an unknown callback. For example: - -```simple -val _hidden_noInline = { int n -> return n+2; }; -val apply_noInline = { {int->int} f,int n -> return f(n); }; -return apply_noInline; -``` - -`FunNode.defaultArg` now supplies the Test class singleton for this receiver, -both during parsing and when Opto reconnects unknown callers. The callback -parameter still reads Start dynamically. The printed-IR regression verifies -that only `` and `apply_noInline` escape; `_hidden_noInline` stays private. - -The function signature retains TypePtr.PTR in this slot. The backends use it -to identify the hidden ABI argument, and callback annotations must not bind -the receiver to the class where the annotation appears. Explicit calls still -supply their actual receiver; instance methods keep their declared object -type. This sharpens the default input, not every abstract pointer: a local -merge of a private object and private callback can also have an abstract -pointer type, so capping arbitrary TypePtr values at outside escapes is unsound. - -## Remaining design question - -Late imported identities also deserve further precision work: identities not -registered when Opto starts lie in the foreign tail. Existing import tests -exercise correctness, but this can remain conservative when bodies arrive -later. This limitation is not repaired by resetting the whole IR. - -## Validation - -The combined `make -k tests CHAPTERS="chapter28a chapter28b chapter29" CTAGS=` -run passes with assertions: 538 active tests in Chapter28a, 578 in Chapter28b, -and 601 in Chapter29. Shared printer and ISA checks pass too. The log is saved -under ignored `build/escape-backport-final.log`. - -`EscapeFlowTest` covers opaque wrappers with three worklist seeds, foreign -callback parameters, private callbacks passed to and returned from native code, -and a CallEnd dependency that responds when only Start's escape set changes. -It also checks that public allocators escape while their private-memory helpers -do not. Class-init tests cover unknown callback cycles; saved-library tests in -28b/29 verify private-function exclusions survive identity remapping. -The existing suites cover nonreturning native calls, class-init cycles, -constructor rejection, serialization, imported callbacks, and three backends. -The four recursive-class examples also pass a separate 16-case worklist-seed -check. Backport IR expectations now retain public allocator Returns instead of -private-memory helper Returns. The String allocation/encoding/export fixtures -in 28a/28b/29 now declare `_hashCodeString` before the public `hashCode` wrapper, -so the implicit return exposes the wrapper. Their measured spill expectations -are 12/8/6 (x86/RISC-V/ARM); native x86 export expects 12. The reordered fixture -also measures 8 on RISC-V before the backport, versus the old order's 6. diff --git a/chapter31/docs/examples/Breakout.smp b/chapter31/docs/examples/Breakout.smp index b1d0b443..d60894ac 100644 --- a/chapter31/docs/examples/Breakout.smp +++ b/chapter31/docs/examples/Breakout.smp @@ -191,7 +191,7 @@ struct Game { for( int i = 0; i < bricks#; i++ ) { if( bricks[i] == 0 ) continue; int row = i/COLS; - i64 x = LEFT+2+(i-row*COLS)*BRICK_DX, y = BRICK_TOP+row*BRICK_DY; + i64 x = LEFT+2+(i%COLS)*BRICK_DX, y = BRICK_TOP+row*BRICK_DY; c.fillRect(x,y,BRICK_W,BRICK_H,COLORS[row]); c.fillRect(x,y,BRICK_W,2,WHITE); } @@ -235,7 +235,7 @@ struct Game { int lastMouse; // Read and act on the controls - val _input = { -> + val _input = { sys.draw.Canvas c -> val gfx = sys.gfx; bool serve = gfx.key(' ') || gfx.button(gfx.LEFT); bool pause = gfx.key('P'); @@ -243,7 +243,7 @@ struct Game { // Keyboard direction and mouse position int direction = (gfx.key(KEY_RIGHT) ? 1 : 0)-(gfx.key(KEY_LEFT) ? 1 : 0); - int mouse = gfx.mouseX(); + int mouse = c.localX(gfx.mouseX()); // Restart requested restartHeld = debounce( restart, restartHeld, { -> _reset(); sys.audio.stop(); } ); @@ -254,7 +254,7 @@ struct Game { pauseHeld = debounce( pause, pauseHeld, { -> paused = !paused; } ); // If no key and mouse moved, set paddle to mouse - if( mouse != lastMouse && direction == 0 && !paused ) { + if( mouse >= 0 && mouse != lastMouse && direction == 0 && !paused ) { _paddle(mouse*1.0); // Set paddle to mouse // If READY and not PLAY, ball tracks paddle directly if( phase == READY ) x = paddle; @@ -291,7 +291,7 @@ struct Game { // Fixed-width decimal labels avoid allocating new strings on every frame. val _number = { !sys.draw.Canvas c, i64 x, i64 y, int value, int digits, int scale, u32 color -> for( int i = 0; i < digits; i++ ) { - c.text(x+(digits-1-i)*4*scale,y,DIGITS[value-value/10*10],scale,color); + c.text(x+(digits-1-i)*4*scale,y,DIGITS[value%10],scale,color); value /= 10; } }; @@ -299,7 +299,7 @@ val _number = { !sys.draw.Canvas c, i64 x, i64 y, int value, int digits, int sca // Short, fading triangle waves; the array initializer builds PCM once at startup. val _tone = { int period -> val samples = new i16[~2400]{int i -> - int phase = i-i/period*period; + int phase = i%period; int triangle = phase < period/2 ? phase : period-phase; return (triangle*4-period)*6000/period*(2400-i)/2400; }; @@ -341,7 +341,12 @@ val main = { u8[~][] args -> while( status == gfx.OK ) { if( gfx.key('Q') || gfx.key(gfx.ESCAPE) ) break; - int direction = g._input(); + // Physics stays in base coordinates; only drawing and input scale. + if( c.resize(gfx.width(),gfx.height()) ) { + g.lastMouse = c.localX(gfx.mouseX()); + frame_ms = 0; + } + int direction = g._input(c); i64 now_ms = sys.time.monotonic(), elapsed_ms = now_ms-last_ms; last_ms = now_ms; // Drop long stalls instead of teleporting the ball after a window drag. @@ -353,7 +358,7 @@ val main = { u8[~][] args -> } if( now_ms >= frame_ms ) { g._draw(c); - status = gfx.present(c.pixels); + status = gfx.presentSize(c.pixels,c.width,c.height); frame_ms = now_ms+FRAME_ms; if( args# > 1 && ++frames == 10 ) break; } diff --git a/chapter31/docs/examples/Clock.smp b/chapter31/docs/examples/Clock.smp index ecf0fae1..fb50f84e 100644 --- a/chapter31/docs/examples/Clock.smp +++ b/chapter31/docs/examples/Clock.smp @@ -20,12 +20,13 @@ val main = { u8[~][] args -> // Main event loop while( status == gfx.OK ) { + bool resized = screen.resize(gfx.width(),gfx.height()); // Did the user press space bar? bool space = gfx.key(' '); // Did the left mouse button go down? bool down = gfx.button(gfx.LEFT); // ANd did it go down over this button? - bool click = button.update(gfx.mouseX(),gfx.mouseY(),down); + bool click = button.update(screen.localX(gfx.mouseX()),screen.localY(gfx.mouseY()),down); // If clicked, flip the clock mode if( click || (space && !held) ) analog = !analog; held = space; @@ -33,12 +34,12 @@ val main = { u8[~][] args -> // Change button label button.label = analog ? "DIGITAL CLOCK" : "ANALOG CLOCK"; // If the next timer event is the every-33-msec event - if( timers.poll(time.monotonic()) == frame_id ) { + if( timers.poll(time.monotonic()) == frame_id || resized ) { // Draw the clock screen and button _draw(screen,time.now(),analog); button.draw(screen,3,GREEN,BACKGROUND,DIM); // Presne the canvas on screen - status = gfx.present(screen.pixels); + status = gfx.presentSize(screen.pixels,screen.width,screen.height); // Testing only: show 5 frames, flip to analog, show 5 more and exit if( args# > 1 ) { frames++; @@ -66,62 +67,61 @@ val _draw = { !sys.draw.Canvas screen, i64 wall_ms, i64 analog -> // a..g bits: top, upper-right, lower-right, bottom, lower-left, upper-left, // middle. Faint unlit bars retain the old LED figure-eight silhouette. +val _digitFont = new u8[~]{ + // 0 1 2 3 4 5 6 7 8 9 + 0x3f, 0x06, 0x5b, 0x4f, 0x66, 0x6d, 0x7d, 0x07, 0x7f, 0x6f +}; +val _digitBars = new u8[~]{ + // x0 y0 x1 y1 + 14, 0, 58, 0, // a: top + 68, 12, 68, 60, // b: upper-right + 68, 84, 68, 132, // c: lower-right + 14, 144, 58, 144, // d: bottom + 4, 84, 4, 132, // e: lower-left + 4, 12, 4, 60, // f: upper-left + 14, 72, 58, 72 // g: middle +}; val _digit = { !sys.draw.Canvas c, int x, int y, i64 digit -> - int bits = digit == 0 ? 0x3f : digit == 1 ? 0x06 : digit == 2 ? 0x5b : - digit == 3 ? 0x4f : digit == 4 ? 0x66 : digit == 5 ? 0x6d : - digit == 6 ? 0x7d : digit == 7 ? 0x07 : digit == 8 ? 0x7f : digit == 9 ? 0x6f : 0; + int bits = 0 <= digit < _digitFont# ? _digitFont[digit] : 0; for( int i = 0; i < 7; i++ ) { u32 color = (bits&(1< - _digit(c,68,166,hour/10); _digit(c,154,166,hour-hour/10*10); - _digit(c,284,166,minute/10); _digit(c,370,166,minute-minute/10*10); - _digit(c,500,166,second/10); _digit(c,586,166,second-second/10*10); + _digit(c, 68,166, hour/10); _digit(c,154,166, hour%10); + _digit(c,284,166,minute/10); _digit(c,370,166,minute%10); + _digit(c,500,166,second/10); _digit(c,586,166,second%10); for( int i = 0; i < 2; i++ ) { c.fillCircle(254+i*216,214,6,GREEN); c.fillCircle(254+i*216,262,6,GREEN); } c.text(272,352,"LOCAL TIME 24H",3,GREEN); }; -// Rational sine approximation, accurate enough for pixel clock geometry. -// Arguments are nonnegative turns; no additional native math dependency. -val _sin = { f64 turn -> - i64 whole = turn; turn -= whole; - bool negative = turn > 0.5; - f64 x = (negative ? turn-0.5 : turn)*6.283185307179586; - f64 product = x*(3.141592653589793-x); - f64 numerator = negative ? -16.0 : 16.0; - return numerator*product/(49.34802200544679-4*product); -}; val _hand = { !sys.draw.Canvas c, f64 turn, int length, int thickness, u32 color -> - int x = 360+_sin(turn)*length, y = 232-_sin(turn+0.25)*length; + f64 angle = turn*2*sys.math.PI; + int x = 360+sys.math.sin(angle)*length, y = 232-sys.math.cos(angle)*length; c.line(360,232,x,y,thickness,color); }; val _analog = { !sys.draw.Canvas c, int hour, int minute, int second, int millisecond -> c.circle(360,232,154,3,GREEN); for( int i = 0; i < 60; i++ ) { - f64 turn = i/60.0; - bool major = i-i/5*5 == 0; + f64 angle = i/60.0*2*sys.math.PI; + bool major = i%5 == 0; int inner = major ? 133 : 143; - int x0 = 360+_sin(turn)*inner, y0 = 232-_sin(turn+0.25)*inner; - int x1 = 360+_sin(turn)*149, y1 = 232-_sin(turn+0.25)*149; + f64 sine = sys.math.sin(angle), cosine = sys.math.cos(angle); + int x0 = 360+sine*inner, y0 = 232-cosine*inner; + int x1 = 360+sine* 149 , y1 = 232-cosine* 149 ; c.line(x0,y0,x1,y1,major ? 3 : 1,GREEN); } c.text(349,100,"12",2,GREEN); c.text(484,227,"3",2,GREEN); - c.text(357,354,"6",2,GREEN); c.text(230,227,"9",2,GREEN); + c.text(357,354, "6",2,GREEN); c.text(230,227,"9",2,GREEN); f64 seconds = second+millisecond/1000.0; f64 minutes = minute+seconds/60.0; - _hand(c,(hour-hour/12*12+minutes/60.0)/12.0,78,8,GREEN); + _hand(c,(hour%12+minutes/60.0)/12.0,78,8,GREEN); _hand(c,minutes/60.0,112,5,GREEN); _hand(c,seconds/60.0,128,2,0xc3ffcb); c.fillCircle(360,232,6,GREEN); diff --git a/chapter31/docs/examples/Graphics.smp b/chapter31/docs/examples/Graphics.smp index 8b251fa2..1878e97d 100644 --- a/chapter31/docs/examples/Graphics.smp +++ b/chapter31/docs/examples/Graphics.smp @@ -2,13 +2,22 @@ // Pass any argument for a short, self-closing test; otherwise close or press Esc. val main = { u8[~][] args -> if( sys.gfx.open("Simple pixels",320,240) != sys.gfx.OK ) return 1; - val pixels = new u32[320*240]; - for( int y = 0; y < 240; y++ ) - for( int x = 0; x < 320; x++ ) - pixels[y*320+x] = (x*255/319 << 16) | (y*255/239 << 8) | 64; - int result = sys.gfx.present(pixels); + val c = new sys.draw.Canvas(320,240); + int result = sys.gfx.OK; + bool dirty = true; int frames = 0; while( result == sys.gfx.OK ) { + if( c.resize(sys.gfx.width(),sys.gfx.height()) ) dirty = true; + if( dirty ) { + // The gradient fills the window, including non-4:3 shapes. + int dx = c.width > 1 ? c.width-1 : 1, dy = c.height > 1 ? c.height-1 : 1; + for( int y = 0; y < c.height; y++ ) + for( int x = 0; x < c.width; x++ ) + c.pixels[y*c.width+x] = (x*255/dx << 16) | (y*255/dy << 8) | 64; + result = sys.gfx.presentSize(c.pixels,c.width,c.height); + if( result != sys.gfx.OK ) break; + dirty = false; + } result = sys.gfx.poll(true); if( args# > 1 && ++frames == 5 ) break; } diff --git a/chapter31/docs/examples/README.md b/chapter31/docs/examples/README.md index 20b644cf..05dcf6cb 100644 --- a/chapter31/docs/examples/README.md +++ b/chapter31/docs/examples/README.md @@ -2,25 +2,30 @@ These programs live beside the documentation so readers can find and run them. Their non-graphical native regression tests run as part of `make tests`. +All four graphical demos support window resizing. Clock, Tic-tac-toe, and +Breakout scale their base layouts uniformly and center them in the window; +mouse input follows the same transform. Breakout keeps its physics in base +coordinates, so resizing preserves the current game and ball speed. The pixel +gradient fills the entire window at its new resolution. The optional [pixel-window example](Graphics.smp) uses MiniFB; see -[graphics setup](../graphics.md). `make run-graphics` opens it explicitly. +[graphics setup](../../src/main/smp/sys/gfx.md). `make run-graphics` opens it explicitly. The [graphical tic-tac-toe](TicTacToeGraphical.smp) uses the Simple -[drawing library](../drawing.md). Run it with -`make run-graphical-tictactoe CTAGS=`; click a cell or press 1–9, R/Space to +[drawing library](../../src/main/smp/sys/draw/README.md). Run it with +`make run-graphical-tictactoe`; click a cell or press 1–9, R/Space to replay, and Q/Escape to quit. The terminal game below remains available. -Optional [background audio](../audio.md) supplies soft move and win/loss cues. +Optional [background audio](../../src/main/smp/sys/audio.md) supplies soft move and win/loss cues. -The [digital and analog clock](Clock.smp) demonstrates the [time library](../time.md), +The [digital and analog clock](Clock.smp) demonstrates the [time library](../../src/main/smp/sys/time/README.md), green seven-segment digits, smooth clock hands, and a reusable software button. -Run `make run-clock CTAGS=`; click the button or press Space to switch faces, +Run `make run-clock`; click the button or press Space to switch faces, and Q/Escape to exit. Both faces show system-local time. -`make clock-example CTAGS=` builds it without starting a window. +`make clock-example` builds it without starting a window. The [Breakout game](Breakout.smp) has 24 columns and 8 rows, with colors and point values by depth: 1 at the bottom through 8 at the top, 864 points total. Clear the wall before losing all three balls. Mouse movement or the arrow keys move the paddle; Space/left click serves, P pauses, R restarts, Q/Escape exits. -Run `make run-breakout CTAGS=` or build only with `make breakout CTAGS=`. +Run `make run-breakout` or build only with `make breakout`. The familiar paddle, serve, and limited-ball rules follow [Atari's Breakout instructions](https://atari.com/pages/breakout). @@ -43,7 +48,7 @@ the boost, and clearing the whole wall without a display or audio device. From `chapter31`, build the tic-tac-toe executable (without starting it): ```sh -make lib tictactoe CTAGS= +make lib tictactoe ``` Run the Windows build from PowerShell: @@ -52,9 +57,15 @@ Run the Windows build from PowerShell: .\build\examples\x86_64_v2_win64\TicTacToe.exe ``` -Or from Cygwin: +Or from Command Prompt (`cmd.exe`): -```sh +```bat +.\build\examples\x86_64_v2_win64\TicTacToe.exe +``` + +Or from Bash (Cygwin, using the Windows build): + +```bash ./build/examples/x86_64_v2_win64/TicTacToe.exe ``` @@ -66,7 +77,7 @@ directory in WSL. Separate Java and native output directories let the Windows and Linux builds coexist: ```sh -make lib tictactoe CLZDIR=build/classes-linux CTAGS= +make lib tictactoe CLZDIR=build/classes-linux ./build/examples/x86_64_v2_SystemV/TicTacToe ``` diff --git a/chapter31/docs/examples/TicTacToeGraphical.smp b/chapter31/docs/examples/TicTacToeGraphical.smp index d3d575a7..72ee6522 100644 --- a/chapter31/docs/examples/TicTacToeGraphical.smp +++ b/chapter31/docs/examples/TicTacToeGraphical.smp @@ -9,7 +9,7 @@ val main = { u8[~][] args -> if( sys.gfx.open("Simple tic-tac-toe",screen.width,screen.height) != sys.gfx.OK ) return 1; sys.audio.open(); // Audio is optional; failure leaves the game silent. _draw(screen,board,-1); - int result = sys.gfx.present(screen.pixels); + int result = sys.gfx.presentSize(screen.pixels,screen.width,screen.height); bool mouseHeld = false, keyHeld = false, replayHeld = false; int hover = -1, frames = 0; @@ -19,8 +19,9 @@ val main = { u8[~][] args -> if( sys.gfx.key('Q') ) break; bool down = sys.gfx.button(sys.gfx.LEFT); bool replay = sys.gfx.key('R') || sys.gfx.key(' '); - int square = _square(sys.gfx.mouseX(),sys.gfx.mouseY()); - bool dirty = square != hover; + bool resized = screen.resize(sys.gfx.width(),sys.gfx.height()); + int square = _square(screen.localX(sys.gfx.mouseX()),screen.localY(sys.gfx.mouseY())); + bool dirty = resized || square != hover; hover = square; if( replay && !replayHeld ) { sys.audio.stop(); _reset(board); dirty = true; } bool digit = false; @@ -41,7 +42,7 @@ val main = { u8[~][] args -> replayHeld = replay; if( dirty ) { _draw(screen,board,hover); - result = sys.gfx.present(screen.pixels); + result = sys.gfx.presentSize(screen.pixels,screen.width,screen.height); } if( args# > 1 && ++frames == 5 ) break; } @@ -143,13 +144,13 @@ val _draw = { !sys.draw.Canvas screen, u8[~] board, int hover -> screen.text(484,145,"CPU",2,0xa2b9b7); screen.fillRect(48,168,504,504,paper); if( !finished && hover >= 0 && hover < 9 && board[hover] == ' ' ) - screen.fillRect(48+(hover-hover/3*3)*168,168+hover/3*168,168,168,0xd9e8de); + screen.fillRect(48+(hover%3)*168,168+hover/3*168,168,168,0xd9e8de); for( int i = 1; i < 3; i++ ) { screen.fillRect(48+i*168-3,168,6,504,ink); screen.fillRect(48,168+i*168-3,504,6,ink); } for( int i = 0; i < 9; i++ ) { - int cx = 132+(i-i/3*3)*168, cy = 252+i/3*168; + int cx = 132+(i%3)*168, cy = 252+i/3*168; if( board[i] == 'X' ) screen.line(cx-38,cy-38,cx+38,cy+38,12,cross).line(cx+38,cy-38,cx-38,cy+38,12,cross); else if( board[i] == 'O' ) screen.circle(cx,cy,48,11,ring); @@ -160,7 +161,7 @@ val _draw = { !sys.draw.Canvas screen, u8[~] board, int hover -> if( line >= 0 ) { int first = line < 3 ? line*3 : line < 6 ? line-3 : line == 6 ? 0 : 2; int last = line < 3 ? first+2 : line < 6 ? first+6 : line == 6 ? 8 : 6; - screen.line(132+(first-first/3*3)*168,252+first/3*168,132+(last-last/3*3)*168,252+last/3*168,5,0xeab64e); + screen.line(132+(first%3)*168,252+first/3*168,132+(last%3)*168,252+last/3*168,5,0xeab64e); } screen.text(48,704,"CLICK A SQUARE OR PRESS 1-9",3,paper); screen.text(48,738,"R OR SPACE REPLAY Q OR ESC QUIT",3,0xa2b9b7); diff --git a/chapter31/docs/graphics.md b/chapter31/docs/graphics.md deleted file mode 100644 index 4977b490..00000000 --- a/chapter31/docs/graphics.md +++ /dev/null @@ -1,132 +0,0 @@ -# Optional graphics - -Simple owns the pixel array and drawing code. [MiniFB](https://github.com/emoon/minifb) -provides a window, input, and pixel presentation. The first interface is -`sys.gfx`: one fixed-size window, operated on the main thread. The -[Graphics example](examples/Graphics.smp) draws a color gradient in Simple. -The [drawing library and graphical tic-tac-toe](drawing.md) build on this pixel -interface. `make run-graphical-tictactoe CTAGS=` builds the optional backend and -opens the game; `make graphical-tictactoe CTAGS=` only builds its executable. -The game run target also builds optional [background audio](audio.md). - -## Default: no graphics dependency - -From `chapter31`, the usual `make release`, `make tests`, and `make tictactoe` -need no MiniFB, graphics headers, OpenGL, CMake, or running display. Nothing -downloads dependencies unless you explicitly request `make libs` or `make init` -(`make lib` remains a setup alias). Build and run targets never use the network. - -`make tests_nographics CTAGS=` runs the entire ordinary suite with -`SIMPLE_MINIFB=off`. This includes the missing-backend tests, which never open -windows. It excludes the interactive `run-graphics` target. - -The runtime contains a small loader using the OS dynamic-library facilities. -It does nothing until `sys.gfx.open`. Without an available backend, `open` -prints a diagnostic to stderr and returns `sys.gfx.ERROR` (-1). Programs can -return a nonzero status or fall back to text; the library does not terminate -the process. Non-graphics programs ignore even a broken graphics configuration. - -## Build the optional backend - -From `chapter31`: - -```sh -make libs CTAGS= # Once while online; fills the persistent lib/ cache. -make graphics graphics-example CTAGS= -make run-graphics CTAGS= -``` - -`libs` downloads the revision pinned in [graphics.mk](../graphics.mk) into -ignored `lib/minifb-.tar.gz` and extracts it under `lib/`. -`graphics` builds only its C framebuffer backend from these local sources. Windows -uses the MinGW-w64 GCC compiler (`x86_64-w64-mingw32-gcc`) and GDI; the rest of -Simple still uses the existing Cygwin GCC. Linux uses GCC and X11 (`libx11-dev` -on Ubuntu), including XWayland on a Wayland desktop. OpenGL, the C++ callback -wrappers, and upstream example programs are omitted. Native Wayland and macOS -builds are not provided here yet. - -Outputs: - -| Platform | Backend | Example | -| --- | --- | --- | -| Windows | `build/release/x86_64_v2_win64/simple_minifb.dll` | `build/examples/x86_64_v2_win64/Graphics.exe` | -| Linux | `build/release/x86_64_v2_SystemV/libsimple_minifb.so` | `build/examples/x86_64_v2_SystemV/Graphics` | - -`MiniFB-LICENSE` is copied alongside the backend; include it when distributing -the library. MiniFB sources remain outside the tracked Simple sources. -The cache survives `make clean`. Editing a makefile or rebuilding a backend -does not fetch or check GitHub. Missing dependencies fail promptly with -instructions to run `make libs` while online. - -`graphics-example` alone builds the executable without requiring MiniFB. It -also demonstrates the diagnostic and exit status 1 when graphics is absent. -`run-graphics` builds both, sets the backend path, and opens a window. Close it -or release Escape to exit. Passing any argument to the executable makes it -close after five polling iterations, for a quick smoke test. - -To run directly from PowerShell: - -```powershell -$env:SIMPLE_MINIFB = (Resolve-Path build/release/x86_64_v2_win64/simple_minifb.dll).Path -.\build\examples\x86_64_v2_win64\Graphics.exe -``` - -From Cygwin bash: - -```sh -export SIMPLE_MINIFB="$PWD/build/release/x86_64_v2_win64/simple_minifb.dll" -./build/examples/x86_64_v2_win64/Graphics.exe -``` - -For WSL, from the repository root: - -```sh -wsl -d Ubuntu-24.04 -- bash -lc 'cd chapter31 && make graphics graphics-example CLZDIR=build/classes-linux CTAGS=' -``` - -Inside WSL, set `SIMPLE_MINIFB` to the full path of the Linux `.so`, then run -the Linux example with a working X11 display. For an automated virtual display: - -```sh -SIMPLE_MINIFB="$PWD/build/release/x86_64_v2_SystemV/libsimple_minifb.so" \ - xvfb-run -a build/examples/x86_64_v2_SystemV/Graphics smoke -``` - -With no `SIMPLE_MINIFB` setting, the runtime searches beside the executable, -then its `../../release/` and `../release/` directories. These cover -the examples and test build layouts regardless of the current directory. -It also checks the current directory, `build/release/`, and -`chapter31/build/release/` relative to the current directory. Thus built -examples such as `Clock.exe` can be launched directly without configuration. - -`SIMPLE_MINIFB` overrides discovery; an invalid explicit path reports an error -without falling back. `SIMPLE_MINIFB=off` disables graphics for headless tests. -An absent, unloadable, or incompatible backend produces a diagnostic. -A backend that loads but cannot create a window also reports an error cleanly. - -## Initial interface - -| Operation | Meaning | -| --- | --- | -| `open(title,width,height)` | Open one window; returns `OK` or `ERROR`. | -| `present(pixels)` | Present a `u32[~]` of exactly `width*height` pixels, packed `0x00RRGGBB`. | -| `poll(wait)` | Process input; `true` waits up to 17ms, waking for input. | -| `wait(timeoutMs)` | Wait for input or timeout, then process events; 0 polls, -1 waits indefinitely. | -| `mouseX()`, `mouseY()` | Current mouse position, origin at upper left. | -| `button(LEFT)`, `key(code)` | Current pressed state; printable keys use uppercase ASCII. | -| `close()` | Release native window and pixel storage; safe to repeat. | - -`present`, `poll`, and `wait` return `OK` (0), `CLOSED` (1, normal close/Escape), or -`ERROR` (-1). Stop polling after either terminal result and call `close`. -The initial input API samples held state; it is not a queue of every transition. - -Waits may return early; values below -1 are errors. Recheck the monotonic -clock after waking. The [time library and animation example](time.md) combine -this wait with cooperative timer deadlines. Backend API version 2 adds the -wait operation; rebuild older MiniFB adapters from the cached sources. - -MiniFB retains its last framebuffer for repaint events. The adapter copies the -Simple array into native-owned storage before presenting; it never retains a -Simple heap pointer. Framebuffer allocation, the copy, and window/input calls -are the only native work here. Drawing primitives and the games can be built -in Simple on top of this boundary. diff --git a/chapter31/docs/intrinsics.md b/chapter31/docs/intrinsics.md deleted file mode 100644 index 3aae39bd..00000000 --- a/chapter31/docs/intrinsics.md +++ /dev/null @@ -1,53 +0,0 @@ -# Fixed-semantics C intrinsics - -An intrinsic is an ordinary C binding with a reserved external symbol and a -fixed signature and meaning. The compiler may replace a known call with ideal -IR nodes; it does not match the spelling of the caller's local variable or a -Simple function with the same name. No new expression syntax is involved. - -The first intrinsics preserve IEEE binary64 representations: - -| External C symbol | Signature | Public alias | -| --- | --- | --- | -| `simple_f64_bits` | `{ f64 -> i64 }` | `sys.math.f64Bits` | -| `simple_f64_from_bits` | `{ i64 -> f64 }` | `sys.math.f64FromBits` | - -```simple -i64 bits = sys.math.f64Bits(1.0); // 0x3ff0000000000000 -f64 value = sys.math.f64FromBits(bits); // 1.0 -int numeric = value; // Numeric conversion, still 1. -``` - -Both operations preserve signed zero, infinities, subnormals, and NaN signs and -payloads, including the signaling bit. They perform no arithmetic and have no -memory effects. An `i64` holds the bit pattern; its sign is irrelevant to the -conversion. Applying either operation followed by the other is an identity. -Floating-point arithmetic between conversions retains its usual semantics and -may change a NaN representation. - -`Intrinsic.java` owns the reserved-symbol table, signatures, effect queries, -inlining, and ideal nodes. Call/CallEnd delegate to it. The cheap inliner checks -intrinsics before requiring a Simple body or Return edge. It validates the -signature and actual arguments, then replaces the complete control/memory/value -state. For these pure operations, control and memory pass through unchanged. -Aliases and imported bindings use the existing external-function identity map. - -Unknown indirect targets keep ordinary calls. `simple_crt.c` supplies real C -definitions, using `memcpy` to preserve representations without aliasing tricks. -These symbols have fixed semantics: a replacement implementation must honor the -same contract. Ordinary C functions remain opaque to the optimizer. - -The ideal nodes support constant folding, inverse cancellation, evaluation, and -serialization. Floating-point constant interning and serialization retain raw -NaN bits. x86 emits `MOVQ` between XMM and integer registers; ARM emits `FMOV`, -and RISC-V emits `FMV.X.D` / `FMV.D.X`. Register allocation may add copies or -spills, and normal module-initialization checks still apply. - -Future intrinsics such as compare-and-swap or fences must define their memory -and escape effects explicitly and expand to nodes with appropriate ordering -dependencies. They must not inherit the pure conversions' passthrough memory -behavior. Atomic operations and hardware square root are not introduced here. - -`make test CLASS=IntrinsicTest CTAGS=` checks folding, representation preservation, -type errors, side effects, indirect C fallback, binary imports, and instruction -selection on all three backends, plus ARM/RISC-V emulation and native x86 execution. diff --git a/chapter31/docs/time.md b/chapter31/docs/time.md deleted file mode 100644 index 10733006..00000000 --- a/chapter31/docs/time.md +++ /dev/null @@ -1,129 +0,0 @@ -# Time and single-threaded animation - -`sys.time` uses bare `i64` values: absolute instants are milliseconds since -the Unix epoch in UTC; durations are milliseconds. Monotonic readings belong -to a separate clock domain. Never subtract a wall-clock reading from a -monotonic deadline. - -## Clocks and waits - -| Call | Result | -| --- | --- | -| `time.now()` | Unix-epoch milliseconds; may jump when the system clock changes. | -| `time.monotonic()` | Monotonic milliseconds for elapsed time and deadlines. | -| `time.nanoTime()` | Monotonic nanoseconds, with the clock's available resolution. | -| `time.sleep(duration_ms)` | Sleep for a nonnegative duration. | -| `time.sleepUntil(deadline_ms)` | Wait for a monotonic millisecond deadline; returns immediately if past. | -| `time.remaining(deadline_ms, current_ms)` | Nonnegative difference, saturating on overflow. | - -Clock errors return `-1`; sleeps return zero on success or `-1` on error, -with `sys.libc.errno()` available. Interrupted sleeps resume rather than -returning early. Wakeup times are approximate, and these calls do not wake a -suspended laptop. Sleeping blocks the one Simple execution thread; use -`gfx.wait` when window input must remain responsive. - -`seconds(n)`, `minutes(n)`, `hours(n)`, and `days(n)` convert signed counts -to milliseconds. `toSeconds(ms)`, `toMinutes(ms)`, `toHours(ms)`, and -`toDays(ms)` truncate toward zero. A duration day is exactly 24 hours, -independent of daylight saving. `toNanos(ms)` and `fromNanos(ns)` convert -between millisecond and nanosecond units. Multiplication overflow returns -`-1`. Constants `SECOND`, `MINUTE`, `HOUR`, and `DAY` are also available, -defined as `1000`, `60*SECOND`, `60*MINUTE`, and `24*HOUR` respectively. -`NANOS_PER_MS` is `1000*1000`. Overflow checks use the shared -`sys.integer.MIN_I64` and `MAX_I64` bounds; `MAX_I32` and `MAX_U32` in that -module also describe the library's array and timer-ID limits. - -## String interpolation - -Time formatting is built into the existing string interpolation syntax: - -| Format | Example | Named style | -| --- | --- | --- | -| `%t(instant)` or `%tF(instant)` | `2026-11-12T00:34:05.123Z` | `time.ISO` | -| `%tr(instant)` | `12:34am` | `time.CLOCK12` | -| `%tR(instant)` | `00:34` | `time.CLOCK24` | -| `%tT(instant)` | `00:34:05` | `time.CLOCK24_SECONDS` | -| `%tD(instant)` | `12/11/26` | `time.DATE` | -| `%tM(duration)` | `02:03.456` | `time.ELAPSED` | - -For example, `"UTC %tR(sys.time.now())"`. Width and left alignment work as -for strings: `%30t(instant)` and `%-30t(instant)`. Precision and numeric flags -are rejected. `%tM` formats a duration, with total minutes rather than wrapping -at an hour; negative durations keep their sign. - -Interpolation uses UTC, making its output stable across machines. -`time.format(instant, style)` is the equivalent library call; -`time.formatLocal(instant, style)` uses the system's local zone. Local ISO -output includes a numeric offset instead of `Z` when nonzero, retaining -offset seconds for historical zones. Invalid calendar values/styles produce -``. The ISO form retains all millisecond bits within the supported -calendar range; short formats intentionally omit information. - -## Calendar values and absolute parsing - -`time.utc(instant)` and `time.local(instant)` return a `DateTime` with fields -`year`, `month`, `day`, `hour`, `minute`, `second`, `millisecond`, `weekday` -(Sunday = 0), `offsetSeconds` (east of UTC), and `daylight`. A zero year means -conversion failed. `time.zoneName(instant)` returns the local abbreviation or -an empty string on error. Local conversion uses the operating system's zone -rules, including DST at that instant; no time-zone database is downloaded. - -`time.makeUTC(year, month, day, hour, minute, second, millisecond)` validates -and constructs an instant, returning `-1` on invalid fields. `time.valid(...)`, -`time.leap(year)`, and `time.monthDays(year, month)` support calendar checks. -Calendar conversion supports Gregorian years 1 through 9999, bounded by -`time.MIN` and `time.MAX`, and rejects leap seconds. - -`time.parse(text)` accepts strict absolute ISO text: -`YYYY-MM-DDTHH:mm:ss[.SSS]Z` or the same with an explicit `+HH:MM`/`-HH:MM` -offset (optionally with `:SS`). Fractions have exactly three digits. No relative -time parsing, implicit local zone, locale-dependent parsing, or named-zone -conversion is provided. Offsets must have hours 00–23 and minutes/seconds 00–59. -Invalid text or an out-of-range result returns `-1`. By design, this sentinel -is indistinguishable from the valid instant `1969-12-31T23:59:59.999Z`; -formatting and calendar conversion still support that instant. - -## Cooperative timers - -Create `val timers = new sys.time.Timers();` on the game thread: - -Timer IDs are `u32`, with `0` reserved for registration failure or no timer due. -Deadlines, delays, and periods remain `i64` milliseconds; their parameter, -field, and local names end in `_ms` to distinguish them from IDs. - -| Operation | Meaning | -| --- | --- | -| `after(delay_ms)` | Register a one-shot timer; return its positive `u32` ID, or `0`. | -| `every(period_ms)` | Register a repeating timer; period must be positive. Returns a `u32` ID, or `0`. | -| `afterAt(current_ms, delay_ms)`, `everyAt(current_ms, period_ms)` | Supply a monotonic reading explicitly, useful for deterministic tests. | -| `cancel(id)` | Remove a timer; return whether it was present. | -| `nextDeadline()` | Earliest monotonic deadline, or `-1` if empty. | -| `poll(current_ms)` | Return the next due `u32` ID, or `0` if none. | - -Poll repeatedly to drain due timers. Deadlines order delivery, then registration -ID breaks ties. Repeating timers advance from their previous deadline, skipping -missed ticks to the first future deadline rather than drifting or replaying a -backlog. Deadline overflow rejects registration or cancels a repeating timer. -IDs are never reused within a collection; registration fails once all nonzero -`u32` IDs have been issued. -There are no callbacks or timer threads: the caller handles each returned ID. - -`gfx.wait(timeout_ms)` processes events after waiting for input or a timeout: -zero polls, `-1` waits indefinitely, values below `-1` fail. It returns the same -`OK`, `CLOSED`, or `ERROR` statuses as `gfx.poll`, and may wake early. Re-read the -monotonic clock after each wake. This allows one thread to handle timers, -input, simulation, and drawing without busy waiting. - -The [digital and analog clock example](examples/Clock.smp) combines these pieces. From -the repository root, with graphics dependencies already cached: - -```sh -make -C chapter31 clock-example CTAGS= # Build without opening a window. -make -C chapter31 run-clock CTAGS= # Build the backend and run. -``` - -Click the button or press Space to switch between green seven-segment digits -and an analog dial with smoothly moving hands. Both display system-local time; -Q/Escape exits. Passing any argument directly to the executable closes it after -ten frames, switching faces halfway through. Hands are computed from the current -time, so delayed frames do not create a simulation catch-up backlog. diff --git a/chapter31/src/main/c/simple_crt.c b/chapter31/src/main/c/simple_crt.c index 39708629..e50042c2 100644 --- a/chapter31/src/main/c/simple_crt.c +++ b/chapter31/src/main/c/simple_crt.c @@ -3,6 +3,7 @@ #include #include #include +#include #include #include @@ -19,6 +20,15 @@ double simple_f64_from_bits(int64_t bits) { return value; } +// Floating remainder's machine instruction uses this memory-preserving helper. +double simple_f64_mod(double x, double y) { + // fmod can set errno for NaN-producing inputs; arithmetic leaves it alone. + int saved_errno = errno; + double result = fmod(x, y); + errno = saved_errno; + return result; +} + // errno may be thread-local or a macro calling a platform accessor. int32_t simple_errno(void) { return errno; } int32_t simple_set_errno(int32_t error) { errno = error; return -1; } diff --git a/chapter31/src/main/c/simple_graphics.c b/chapter31/src/main/c/simple_graphics.c index 40d66ba9..a35c28a6 100644 --- a/chapter31/src/main/c/simple_graphics.c +++ b/chapter31/src/main/c/simple_graphics.c @@ -74,7 +74,8 @@ static int load_graphics(void) { if (!candidate || candidate->version != SIMPLE_GRAPHICS_VERSION || !candidate->open || !candidate->present || !candidate->poll || !candidate->mouse_x || !candidate->mouse_y || !candidate->button || - !candidate->key || !candidate->close || !candidate->wait) { + !candidate->key || !candidate->close || !candidate->wait || + !candidate->width || !candidate->height || !candidate->present_size) { fprintf(stderr, "Simple graphics: incompatible MiniFB backend '%s'. Rebuild with make graphics.\n", path); dlclose(library); library = NULL; @@ -93,6 +94,11 @@ int32_t simple_gfx_open(const char *title, uint32_t width, uint32_t height) { int32_t simple_gfx_present(const uint32_t *pixels, uint32_t count) { return api ? api->present(pixels, count) : -1; } +int32_t simple_gfx_present_size(const uint32_t *pixels, uint32_t count, uint32_t width, uint32_t height) { + return api ? api->present_size(pixels, count, width, height) : -1; +} +uint32_t simple_gfx_width(void) { return api ? api->width() : 0; } +uint32_t simple_gfx_height(void) { return api ? api->height() : 0; } int32_t simple_gfx_poll(int32_t wait) { return api ? api->poll(wait) : -1; } int32_t simple_gfx_mouse_x(void) { return api ? api->mouse_x() : 0; } int32_t simple_gfx_mouse_y(void) { return api ? api->mouse_y() : 0; } diff --git a/chapter31/src/main/c/simple_graphics.h b/chapter31/src/main/c/simple_graphics.h index 370256be..d19cac46 100644 --- a/chapter31/src/main/c/simple_graphics.h +++ b/chapter31/src/main/c/simple_graphics.h @@ -15,6 +15,9 @@ struct simple_graphics_api { int32_t (*key)(int32_t); void (*close)(void); int32_t (*wait)(int64_t); + uint32_t (*width)(void); + uint32_t (*height)(void); + int32_t (*present_size)(const uint32_t *, uint32_t, uint32_t, uint32_t); }; -#define SIMPLE_GRAPHICS_VERSION 2 +#define SIMPLE_GRAPHICS_VERSION 3 #endif diff --git a/chapter31/src/main/c/simple_minifb.c b/chapter31/src/main/c/simple_minifb.c index 2117f0d2..86f110c3 100644 --- a/chapter31/src/main/c/simple_minifb.c +++ b/chapter31/src/main/c/simple_minifb.c @@ -14,11 +14,19 @@ #include "x11/WindowData_X11.h" #endif -// One fixed-size window for now. No Simple pointer survives a native call: +// One resizable window. No Simple pointer survives a native call: // MiniFB retains its last draw buffer for OS repaint events, so copy it here. static struct mfb_window *window; static uint32_t *frame; static uint32_t width, height; +static size_t capacity; + +static uint32_t window_width(void) { return window ? mfb_get_window_width(window) : 0; } +static uint32_t window_height(void) { return window ? mfb_get_window_height(window) : 0; } + +static void resize_window(struct mfb_window *w, int x, int y) { + if (x > 0 && y > 0) mfb_set_viewport(w, 0, 0, (unsigned)x, (unsigned)y); +} // The C-only build never installs the upstream C++ callback wrappers. void release_cpp_stub(struct mfb_window *unused) { (void)unused; } @@ -31,6 +39,7 @@ static void close_window(void) { } free(frame); frame = NULL; + capacity = 0; } static int32_t open_window(const char *title, uint32_t w, uint32_t h) { @@ -44,7 +53,8 @@ static int32_t open_window(const char *title, uint32_t w, uint32_t h) { fprintf(stderr, "Simple graphics: cannot allocate the display buffer.\n"); return -1; } - window = mfb_open(title, w, h); + capacity = (size_t)w * h; + window = mfb_open_ex(title, w, h, MFB_WF_RESIZABLE); if (!window) { fprintf(stderr, "Simple graphics: MiniFB could not open a window (is a graphical display available?).\n"); close_window(); @@ -52,6 +62,7 @@ static int32_t open_window(const char *title, uint32_t w, uint32_t h) { } width = w; height = h; + mfb_set_resize_callback(window, resize_window); return 0; } @@ -67,14 +78,29 @@ static int32_t status(mfb_update_state state) { return -1; } -static int32_t present(const uint32_t *pixels, uint32_t count) { +static int32_t present_size(const uint32_t *pixels, uint32_t count, uint32_t w, uint32_t h) { if (!window) return 1; - if (!pixels || count != (uint64_t)width * height) { + if (!pixels || !w || !h || w > UINT32_MAX / 4 || + count != (uint64_t)w * h || (uint64_t)w * h > SIZE_MAX / 4) { fprintf(stderr, "Simple graphics: pixel array length must equal width * height.\n"); return -1; } + if (count > capacity) { + uint32_t *larger = realloc(frame, (size_t)count * sizeof(*frame)); + if (!larger) { + fprintf(stderr, "Simple graphics: cannot resize the display buffer.\n"); + return -1; + } + frame = larger; + capacity = count; + } memcpy(frame, pixels, (size_t)count * sizeof(*frame)); - return status(mfb_update_ex(window, frame, width, height)); + return status(mfb_update_ex(window, frame, w, h)); +} + +// Compatibility for clients drawing at their original resolution. +static int32_t present(const uint32_t *pixels, uint32_t count) { + return present_size(pixels, count, width, height); } static int32_t wait_events(int64_t timeout) { @@ -109,7 +135,8 @@ static int32_t key(int32_t k) { static const struct simple_graphics_api api = { SIMPLE_GRAPHICS_VERSION, open_window, present, poll_events, - mouse_x, mouse_y, button, key, close_window, wait_events + mouse_x, mouse_y, button, key, close_window, wait_events, + window_width, window_height, present_size }; #ifdef _WIN32 __declspec(dllexport) diff --git a/chapter31/src/main/java/com/seaofnodes/simple/codegen/GlobalCodeMotion.java b/chapter31/src/main/java/com/seaofnodes/simple/codegen/GlobalCodeMotion.java index 86cb2e98..83c0677d 100644 --- a/chapter31/src/main/java/com/seaofnodes/simple/codegen/GlobalCodeMotion.java +++ b/chapter31/src/main/java/com/seaofnodes/simple/codegen/GlobalCodeMotion.java @@ -141,10 +141,11 @@ public abstract class GlobalCodeMotion { if( def!=null && !(def instanceof PhiNode) ) _schedEarly(def,code,start); - // An existing edge 0 already supplies control (or a Phi/Proj binding). - if( n.in(0)==null ) { + // A memory op's control is a lower bound, not a complete early schedule: + // instruction selection may have folded in an operand defined later. + if( n.in(0)==null || n instanceof MemOpNode ) { // Schedule at deepest input - CFGNode early = start; // Maximally early, lowest idepth + CFGNode early = n.in(0) instanceof CFGNode ctrl ? ctrl : start; for( int i=1; i early.idepth() ) early = n.in(i).cfg0(); // Latest/deepest input @@ -251,6 +252,9 @@ public abstract class GlobalCodeMotion { if( use != null ) lca = use_block(n,use, late).domLCA(lca,null); + assert lca!=null && early.dominates(lca,null) : + "Early schedule must dominate uses of "+n.getClass().getSimpleName()+"#"+n._nid; + // Loads may need anti-dependencies, raising their LCA if( n instanceof MemOpNode load && load._isLoad ) lca = find_anti_dep(lca,load,early,late,anti, antideps); diff --git a/chapter31/src/main/java/com/seaofnodes/simple/codegen/ListScheduler.java b/chapter31/src/main/java/com/seaofnodes/simple/codegen/ListScheduler.java index c3b603e5..f90d8d4e 100644 --- a/chapter31/src/main/java/com/seaofnodes/simple/codegen/ListScheduler.java +++ b/chapter31/src/main/java/com/seaofnodes/simple/codegen/ListScheduler.java @@ -49,7 +49,7 @@ public abstract class ListScheduler { else computeSingleRDef(bb,n); - if( n instanceof NewNode || n instanceof CallNode ) + if( n instanceof NewNode || n instanceof CallNode || n instanceof ModFNode ) bb.fun()._hasCalls = true; return this; } diff --git a/chapter31/src/main/java/com/seaofnodes/simple/codegen/RegAlloc.java b/chapter31/src/main/java/com/seaofnodes/simple/codegen/RegAlloc.java index 1b335c50..303fd355 100644 --- a/chapter31/src/main/java/com/seaofnodes/simple/codegen/RegAlloc.java +++ b/chapter31/src/main/java/com/seaofnodes/simple/codegen/RegAlloc.java @@ -184,6 +184,7 @@ public class RegAlloc { if( bb instanceof CallEndMach cend ) cend.cacheRegs(_code); for( Node n : bb._outputs ) if( n instanceof NewNode nnn ) nnn.cacheRegs(_code); + else if( n instanceof ModFNode mod ) mod.cacheRegs(_code); } // Expensive assert: useful when chasing cross-function allocator edges. //assert verifyFunctionLocalEdges(); @@ -680,7 +681,14 @@ public class RegAlloc { if( cfg==def.cfg0() && def.nOuts()==1 && !singleReg ) return; } - makeSplit(def,kind,round,lrg,umask).insertBefore(n, i); + // If isolating a loop Phi's uses did not relieve pressure, cloning its + // constant input again cannot help: it still forces the Phi into a GPR. + // A real transfer on this retry lets the Phi live on the stack. + Node split = n instanceof PhiNode phi && phi.region() instanceof LoopNode && + lrg._machUse instanceof SplitNode prior && prior._round X86.call(enc); + case "arm" -> enc.add4(Arm64.b(Arm64.OP_CALL,0)); + case "riscv" -> { + enc.add4(RiscV.u_type(RiscV.OP_AUIPC,riscv.T0,0)); + enc.add4(RiscV.i_type(RiscV.OP_JALR,riscv.RPC,0,riscv.T0,0)); + } + default -> throw new IllegalStateException(machine().name()); + } + } + @Override public void asm(CodeGen code, SB sb) { + sb.p(code.reg(this)).p(" = ").p(code.reg(in(1))).p(" % ").p(code.reg(in(2))); + } + @Override public String comment() { return "call simple_f64_mod"; } +} diff --git a/chapter31/src/main/java/com/seaofnodes/simple/node/ModNode.java b/chapter31/src/main/java/com/seaofnodes/simple/node/ModNode.java new file mode 100644 index 00000000..7c1a9238 --- /dev/null +++ b/chapter31/src/main/java/com/seaofnodes/simple/node/ModNode.java @@ -0,0 +1,16 @@ +package com.seaofnodes.simple.node; + +import com.seaofnodes.simple.type.TypeInteger; + +public class ModNode extends ArithNode { + public ModNode(Node lhs, Node rhs) { super(null,lhs,rhs); } + public ModNode(Node lhs, Node rhs, byte mode) { super(null,lhs,rhs,mode); } + @Override public Tag serialTag() { return Tag.Mod; } + @Override public String op() { return "%"; } + @Override boolean allowFloat() { return true; } + + @Override long doOp(long x, long y) { return y==0 ? 0 : x%y; } + @Override double doOp(double x, double y) { return x%y; } + @Override TypeInteger doOp(TypeInteger x, TypeInteger y) { return TypeInteger.BOT; } + @Override Node copy(Node lhs, Node rhs) { return new ModNode(lhs,rhs,_mode); } +} diff --git a/chapter31/src/main/java/com/seaofnodes/simple/node/Node.java b/chapter31/src/main/java/com/seaofnodes/simple/node/Node.java index d4c0794c..ad4f47e0 100644 --- a/chapter31/src/main/java/com/seaofnodes/simple/node/Node.java +++ b/chapter31/src/main/java/com/seaofnodes/simple/node/Node.java @@ -77,7 +77,7 @@ public abstract class Node extends BaseNode implements Cloneable { New,Never,Not,Or,Parm,Phi,Proj,PtrToInt, ReadOnly,Return,Region,RoundF32, Sar,Shl,Shr,Start,StartCU,StopCU,Stop,Store,Sub, - ToInteger,ToFloat,XCtrl,Xor,F64Bits,F64FromBits; + ToInteger,ToFloat,XCtrl,Xor,F64Bits,F64FromBits,Mod; public static final Tag[] VALS = values(); public Node make( BAOS bais, String[] strs, Type[] types, GlobalBits fileAliases, GlobalBits aliases ) { return switch(this) { @@ -117,6 +117,7 @@ public abstract class Node extends BaseNode implements Cloneable { case Call -> CallNode.make(bais,strs); case CallEnd-> CallEndNode.make(bais ,types); case CLInit -> new CLInitNode(bais,strs); + case Mod -> new ModNode(null,null,(byte)bais.packed1()); case CProj -> CProjNode.make(bais,strs); case Con -> ConstantNode.make(bais ,types); case Escape-> EscapeNode.make(bais ,types); diff --git a/chapter31/src/main/java/com/seaofnodes/simple/node/cpus/arm/ModARM.java b/chapter31/src/main/java/com/seaofnodes/simple/node/cpus/arm/ModARM.java new file mode 100644 index 00000000..bd29ba3f --- /dev/null +++ b/chapter31/src/main/java/com/seaofnodes/simple/node/cpus/arm/ModARM.java @@ -0,0 +1,29 @@ +package com.seaofnodes.simple.node.cpus.arm; + +import com.seaofnodes.isa.Arm64; +import com.seaofnodes.simple.codegen.*; +import com.seaofnodes.simple.node.*; +import com.seaofnodes.simple.util.SB; + +public class ModARM extends MachConcreteNode implements MachNode { + private static final RegMask REGS=new RegMask(arm.WR_BITS & ~(1L< new CProjNode(c); case ConstantNode con-> con(con); case DivNode div -> div.mode()==2 ? new DivFARM(div) : new DivARM(div); + case ModNode mod -> mod.mode()==2 ? new ModFNode(mod) : new ModARM(mod); case EscapeNode esc -> new EscapeNode(esc); case FunNode fun -> new FunARM(fun); case FunPtrNode fptr -> fptr(fptr); diff --git a/chapter31/src/main/java/com/seaofnodes/simple/node/cpus/riscv/DivRISC.java b/chapter31/src/main/java/com/seaofnodes/simple/node/cpus/riscv/DivRISC.java index 515ffa47..691979ec 100644 --- a/chapter31/src/main/java/com/seaofnodes/simple/node/cpus/riscv/DivRISC.java +++ b/chapter31/src/main/java/com/seaofnodes/simple/node/cpus/riscv/DivRISC.java @@ -1,17 +1,26 @@ package com.seaofnodes.simple.node.cpus.riscv; +import com.seaofnodes.isa.RiscV; import com.seaofnodes.simple.util.SB; import com.seaofnodes.simple.codegen.*; import com.seaofnodes.simple.node.*; public class DivRISC extends MachConcreteNode implements MachNode{ - public DivRISC(Node div) {super(div);} - @Override public String op() { return "div"; } + private final boolean _mod; + public DivRISC(Node div) {super(div); _mod=div instanceof ModNode;} + @Override public String op() { return _mod ? "mod" : "div"; } @Override public RegMask regmap(int i) { return riscv.RMASK; } @Override public RegMask outregmap() { return riscv.WMASK; } - @Override public void encoding( Encoding enc ) { riscv.r_type(enc,this,4,1); } + @Override public void encoding( Encoding enc ) { + // RISC-V returns -1 for DIV by zero, and the dividend for REM by zero. + // Both ideal operations instead return zero. + enc.add4(RiscV.b_type(RiscV.OP_BRANCH,1,enc.reg(in(2)),(short)riscv.ZERO,12)); + enc.add4(RiscV.i_type(RiscV.OP_IMM,enc.reg(this),0,riscv.ZERO,0)); + enc.add4(RiscV.j_type(RiscV.OP_JAL,riscv.ZERO,8)); + riscv.r_type(enc,this,_mod ? 6 : 4,1); + } @Override public void asm(CodeGen code, SB sb) { - sb.p(code.reg(this)).p(" = ").p(code.reg(in(1))).p(" / ").p(code.reg(in(2))); + sb.p(code.reg(this)).p(" = ").p(code.reg(in(1))).p(_mod ? " % " : " / ").p(code.reg(in(2))); } } diff --git a/chapter31/src/main/java/com/seaofnodes/simple/node/cpus/riscv/riscv.java b/chapter31/src/main/java/com/seaofnodes/simple/node/cpus/riscv/riscv.java index 976d1a52..70585732 100644 --- a/chapter31/src/main/java/com/seaofnodes/simple/node/cpus/riscv/riscv.java +++ b/chapter31/src/main/java/com/seaofnodes/simple/node/cpus/riscv/riscv.java @@ -222,6 +222,7 @@ public class riscv extends Machine { case CProjNode c -> new CProjNode(c); case ConstantNode con -> con(con); case DivNode div -> div.mode()==2 ? new DivFRISC(div) : new DivRISC(div); + case ModNode mod -> mod.mode()==2 ? new ModFNode(mod) : new DivRISC(mod); case EscapeNode esc -> new EscapeNode(esc); case FunNode fun -> new FunRISC(fun); case FunPtrNode fptr -> fptr(fptr); diff --git a/chapter31/src/main/java/com/seaofnodes/simple/node/cpus/x86_64_v2/CmpX86.java b/chapter31/src/main/java/com/seaofnodes/simple/node/cpus/x86_64_v2/CmpX86.java index 7faea17b..f8e652df 100644 --- a/chapter31/src/main/java/com/seaofnodes/simple/node/cpus/x86_64_v2/CmpX86.java +++ b/chapter31/src/main/java/com/seaofnodes/simple/node/cpus/x86_64_v2/CmpX86.java @@ -7,6 +7,12 @@ import com.seaofnodes.simple.util.SB; public class CmpX86 extends MachConcreteNode implements MachNode { CmpX86( Node add ) { super(add); } + private CmpX86(CmpX86 cmp) { + super((Node)null); + addDef(null); + addDef(cmp.in(1)); + addDef(cmp.in(2)); + } @Override public String op() { return "cmp"; } @Override public RegMask regmap(int i) { return x86_64_v2.RMASK; } @Override public RegMask outregmap() { return x86_64_v2.FLAGS_MASK; } @@ -16,6 +22,7 @@ public class CmpX86 extends MachConcreteNode implements MachNode { // compared to some normal registers - and those normal registers might not // be spilling! @Override public boolean isClone() { return true; } + @Override public Node copy() { return new CmpX86(this); } @Override public void encoding( Encoding enc ) { X86.reg(enc,0x3B,enc.reg(in(1)),enc.reg(in(2))); diff --git a/chapter31/src/main/java/com/seaofnodes/simple/node/cpus/x86_64_v2/DivX86.java b/chapter31/src/main/java/com/seaofnodes/simple/node/cpus/x86_64_v2/DivX86.java index 9f375a80..7607913f 100644 --- a/chapter31/src/main/java/com/seaofnodes/simple/node/cpus/x86_64_v2/DivX86.java +++ b/chapter31/src/main/java/com/seaofnodes/simple/node/cpus/x86_64_v2/DivX86.java @@ -6,20 +6,42 @@ import com.seaofnodes.simple.node.*; import com.seaofnodes.simple.util.SB; public class DivX86 extends MachConcreteNode implements MachNode { - DivX86( Node div ) { super(div); } - @Override public String op() { return "div"; } + private final boolean _mod; + DivX86( Node div ) { super(div); _mod=div instanceof ModNode; } + @Override public String op() { return _mod ? "mod" : "div"; } @Override public RegMask regmap(int i) { return (i==1) ? x86_64_v2.RAX_MASK : x86_64_v2.DIV_MASK; } - @Override public RegMask outregmap() { return x86_64_v2.RAX_MASK; } - @Override public RegMask killmap() { return x86_64_v2.RDX_MASK; } + @Override public RegMask outregmap() { return _mod ? x86_64_v2.RDX_MASK : x86_64_v2.RAX_MASK; } + @Override public RegMask killmap() { + return new RegMask((1L<<(_mod ? x86_64_v2.RAX : x86_64_v2.RDX)) | (1L< new GuardMach(guard); case ConstantNode con -> con(con); case DivNode div -> div.mode()==2 ? new DivFX86(div) : new DivX86(div); + case ModNode mod -> mod.mode()==2 ? new ModFNode(mod) : new DivX86(mod); case EscapeNode esc -> new EscapeNode(esc); case FunNode fun -> new FunX86(fun); case FunPtrNode fptr -> fptr(fptr); @@ -354,7 +357,7 @@ public class x86_64_v2 extends Machine { return new AddFX86(add); Node lhs = add.in(1); Node rhs = add.in(2); - if( lhs instanceof LoadNode ld && ld.nOuts() == 1 && ld.declaredType().log_size() >= 3) + if( lhs instanceof LoadNode ld && ld.declaredType().log_size() >= 3 && canFoldLoad(ld,rhs) ) return new AddMemX86(add, address(ld), ld.ptr(), idx, off, scale, 0, rhs); // Attempt a full LEA-style break down. // Returns one of AddX86, AddIX86, LeaX86, or LHS @@ -430,11 +433,11 @@ public class x86_64_v2 extends Machine { // Since cmp does not record a BOP, SetX/Jmp need to know if the CMP is swapped. // Vs memory - if( lhs instanceof LoadNode ld && ld.nOuts() == 1 && rhs._type.isa(ld.declaredType()) ) + if( lhs instanceof LoadNode ld && rhs._type.isa(ld.declaredType()) && canFoldLoad(ld,rhs) ) return new CmpMemX86(bool, address(ld), ld.ptr(), idx, off, scale, imm(rhs), val, false); // Operands swap in the encoding directly, no need for Set/Jmp to swap `bop` - if( rhs instanceof LoadNode ld && ld.nOuts() == 1 && lhs._type.isa(ld.declaredType()) && + if( rhs instanceof LoadNode ld && lhs._type.isa(ld.declaredType()) && canFoldLoad(ld,lhs) && (!(lhs instanceof ConstantNode con && con._con instanceof TypeInteger ti && imm32(ti.value())) || bool.op()=="==" || bool.op()=="!=") ) return new CmpMemX86(bool, address(ld), ld.ptr(), idx, off, scale, imm(lhs), val, true ); @@ -451,6 +454,25 @@ public class x86_64_v2 extends Machine { return new CmpX86(bool); } + // The other operand must not depend on a writer which must follow this + // load. Fusing them would move the read across that write (or form a + // scheduling cycle). Control dependencies count too, including calls. + private static boolean canFoldLoad(LoadNode load, Node value) { + if( load.nOuts()!=1 ) return false; + Ary writers=load.antiDeps(new Ary<>(Node.class)); + if( writers.isEmpty() ) return true; + var seen=new IdentityHashMap(); + Ary work=new Ary<>(Node.class); + work.push(value); + while( !work.isEmpty() ) { + Node n=work.pop(); + if( seen.put(n,Boolean.TRUE)!=null ) continue; + if( writers.find(n)!=-1 ) return false; + for( Node def : n._inputs ) if( def!=null ) work.push(def); + } + return true; + } + private Node con( ConstantNode con ) { if( !con._con.isConstant() ) return ConstantNode.raw(con); // Default unknown caller inputs diff --git a/chapter31/src/main/java/com/seaofnodes/simple/parser/Construction.java b/chapter31/src/main/java/com/seaofnodes/simple/parser/Construction.java index 6dec8ac1..7797cae4 100644 --- a/chapter31/src/main/java/com/seaofnodes/simple/parser/Construction.java +++ b/chapter31/src/main/java/com/seaofnodes/simple/parser/Construction.java @@ -56,7 +56,8 @@ import com.seaofnodes.simple.util.Ary; * binding denotes the allocator. Private-memory Parms therefore need no * fictitious external default or constructor-specific transfer function. * InitView and Construct are erased by the existing TypeCheck walk. There is - * no extra construction pass; see docs/construction-groups.md. + * no extra construction pass; see chapter29/docs/construction-groups.md + * from the repository root, and chapter29/README.md for the introduction. */ final class Construction { private final Parser P; diff --git a/chapter31/src/main/java/com/seaofnodes/simple/parser/Expressions.java b/chapter31/src/main/java/com/seaofnodes/simple/parser/Expressions.java index 6486aba8..ffc96f57 100644 --- a/chapter31/src/main/java/com/seaofnodes/simple/parser/Expressions.java +++ b/chapter31/src/main/java/com/seaofnodes/simple/parser/Expressions.java @@ -233,7 +233,7 @@ final class Expressions { * Parse an multiplicativeExpr expression * *
-     *     multiplicativeExpr : unaryExpr (('*' | '/') unaryExpr)*
+     *     multiplicativeExpr : unaryExpr (('*' | '/' | '%') unaryExpr)*
      * 
* @return a multiply expression {@link Node}, never {@code null} */ @@ -242,6 +242,7 @@ final class Expressions { while( true ) { if( P.match("*") ) lhs = new MulNode(lhs,null); else if( P.match("/") ) lhs = new DivNode(lhs,null); + else if( P.match("%") ) lhs = new ModNode(lhs,null); else break; lhs.setDef(2,parseUnary()); lhs = P.peep(lhs); @@ -341,6 +342,7 @@ final class Expressions { case '-' -> new SubNode(lhs,rhs); case '*' -> new MulNode(lhs,rhs); case '/' -> new DivNode(lhs,rhs); + case '%' -> new ModNode(lhs,rhs); case '|' -> new OrNode(null,lhs,rhs); case '&' -> new AndNode(null,lhs,rhs); case '^' -> new XorNode(P.loc(),lhs,rhs); diff --git a/chapter31/src/main/java/com/seaofnodes/simple/parser/Lexer.java b/chapter31/src/main/java/com/seaofnodes/simple/parser/Lexer.java index 62dd054e..8633f2be 100644 --- a/chapter31/src/main/java/com/seaofnodes/simple/parser/Lexer.java +++ b/chapter31/src/main/java/com/seaofnodes/simple/parser/Lexer.java @@ -325,7 +325,7 @@ public class Lexer { // private boolean isPunctuation(char ch) { - return "=;[]<>()+-/*&|^".indexOf(ch) != -1; + return "=;[]<>()+-/*%&|^".indexOf(ch) != -1; } private String parsePunctuation() { @@ -350,7 +350,7 @@ public class Lexer { if( match(">>=" ) ) return SAR; if( _position+2 >= _input.length ) return 0; char ch0 = (char)_input[_position]; - if( "+-/*&|^".indexOf(ch0) == -1 ) return 0; + if( "+-/*%&|^".indexOf(ch0) == -1 ) return 0; char ch1 = (char)_input[_position+1]; if( ch1 == '=' ) { _position += 2; return ch0; } if( isIdLetter((char)_input[_position+2]) ) return 0; diff --git a/chapter31/src/main/smp/sys.smp b/chapter31/src/main/smp/sys.smp index 3fb8d94b..58896f33 100644 --- a/chapter31/src/main/smp/sys.smp +++ b/chapter31/src/main/smp/sys.smp @@ -8,7 +8,7 @@ val aryi64 = aryi64; // Variable sized array of i64 val aryu8 = aryu8; // Variable sized array of u8 val char = char; // Character utilities val integer = integer; // Integer bounds -val math = math; // Floating-point representation primitives +val math = math; // Math functions, constants, and float representations val io = io; // IO library val gfx = gfx; // Optional pixel window (MiniFB) val draw = draw; // Software raster drawing in Simple diff --git a/chapter31/src/main/smp/sys/audio.md b/chapter31/src/main/smp/sys/audio.md new file mode 100644 index 00000000..bb2ad77c --- /dev/null +++ b/chapter31/src/main/smp/sys/audio.md @@ -0,0 +1,84 @@ +# Optional background audio + +[Chapter 31](../../../../README.md#graphics-and-sound) introduces the library. +The Simple API is implemented in [audio.smp](audio.smp), with the native adapter +in [simple_miniaudio.c](../../c/simple_miniaudio.c). + +`sys.audio` uses [miniaudio](https://github.com/mackron/miniaudio) through an +optional native C backend. Playback runs on its own thread; the game keeps +processing input and drawing. No Python, CMake, codec packages, or sound files +are needed. Default builds/tests never download miniaudio or open a device. + +From `chapter31`: + +```sh +make libs # Once while online +make audio +make run-graphical-tictactoe +``` + +The last command builds both optional backends and runs a tictactoe game with +sounds. Accepted moves get a quiet 70ms sine boop. A player win gets a 480ms +rising C-E-G celebration; a CPU win reverses the notes + +For direct execution from `chapter31`, configure both backends and launch the +game using your shell. + +PowerShell: + +```powershell +$env:SIMPLE_MINIFB = (Resolve-Path build/release/x86_64_v2_win64/simple_minifb.dll).Path +$env:SIMPLE_MINIAUDIO = (Resolve-Path build/release/x86_64_v2_win64/simple_miniaudio.dll).Path +.\build\examples\x86_64_v2_win64\TicTacToeGraphical.exe +``` + +Command Prompt (`cmd.exe`): + +```bat +set "SIMPLE_MINIFB=%CD%\build\release\x86_64_v2_win64\simple_minifb.dll" +set "SIMPLE_MINIAUDIO=%CD%\build\release\x86_64_v2_win64\simple_miniaudio.dll" +.\build\examples\x86_64_v2_win64\TicTacToeGraphical.exe +``` + +Bash (Cygwin, using the Windows build): + +```bash +export SIMPLE_MINIFB="$PWD/build/release/x86_64_v2_win64/simple_minifb.dll" +export SIMPLE_MINIAUDIO="$PWD/build/release/x86_64_v2_win64/simple_miniaudio.dll" +./build/examples/x86_64_v2_win64/TicTacToeGraphical.exe +``` + +Linux uses `libsimple_miniaudio.so` in the corresponding release directory. +`SIMPLE_MINIAUDIO` must name the full backend path. Unset it or set it to `off` +for silent play. An unavailable audio device returns `ERROR` and the game +continues. Audio and graphics can be configured independently. + +| Operation | Meaning | +| --- | --- | +| `open()` | Open output and generate built-in sounds; `OK` (0) or `ERROR` (-1). Repeated open is safe. | +| `boop()`, `win()`, `lose()` | Play a built-in cue; same as `play(BOOP/WIN/LOSE)`. | +| `load(samples)` | Copy `i16[~]` mono PCM at `RATE` (48000Hz); return handle or `ERROR`. | +| `play(handle)` | Start/restart, replacing the current sound. Return `OK` or `ERROR`. | +| `stop()` | Stop playback; safe before open/after close. | +| `playing()` | Whether samples remain to submit; final device buffering may remain. | +| `close()` | Join the audio thread and free device/buffers; safe to repeat. | + +All calls belong on the main/game thread. Load custom sounds at startup: +there are 28 custom slots, each up to ten seconds, retained until close. +Custom handles must be reloaded after close/reopen. Signed samples range +from -32768 to 32767; quiet effects should use much smaller amplitudes. +Native code copies the array and never retains a Simple heap pointer or calls +Simple from the audio thread. Playback itself neither allocates nor waits for +the sound duration. This first interface plays one sound at a time. + +`audio.mk` pins miniaudio 0.11.23, cached under `lib/miniaudio-0.11.23/` by +`make libs` (or `init`; `lib` remains a setup alias). Only these explicit +setup targets can download dependencies. All builds, runs, and tests use local +copies, surviving `make clean`; missing cache entries fail promptly with setup +instructions. Windows uses the existing MinGW-w64 compiler; Linux uses GCC and +system pthread/math/dl libraries. No audio development headers need +installing. The upstream header includes its public-domain and MIT-0 license +options, copied beside the backend as `miniaudio-LICENSE`. `make test-audio` +builds the backend checks from the local cache and runs a real audio thread +with miniaudio's silent null device; normal tests exercise the loader and game +without hardware. diff --git a/chapter31/src/main/smp/sys/audio.smp b/chapter31/src/main/smp/sys/audio.smp index 89e6dfa9..5dbe63a3 100644 --- a/chapter31/src/main/smp/sys/audio.smp +++ b/chapter31/src/main/smp/sys/audio.smp @@ -1,4 +1,5 @@ // Optional background audio. All API calls belong on the game/main thread. +// API and launch reference: audio.md beside this file. int OK = 0; int ERROR = -1; int BOOP = 1; diff --git a/chapter31/src/main/smp/sys/draw.smp b/chapter31/src/main/smp/sys/draw.smp index 2a8b6117..92bf04b7 100644 --- a/chapter31/src/main/smp/sys/draw.smp +++ b/chapter31/src/main/smp/sys/draw.smp @@ -1,4 +1,5 @@ // Software raster drawing. No window or native calls; pixels are packed RGB (0x00RRGGBB). +// API reference: draw/README.md. u32 BLACK = 0x000000; u32 WHITE = 0xffffff; u32 RED = 0xff0000; diff --git a/chapter31/src/main/smp/sys/draw/Canvas.smp b/chapter31/src/main/smp/sys/draw/Canvas.smp index 9ba3514a..5ec7c9ef 100644 --- a/chapter31/src/main/smp/sys/draw/Canvas.smp +++ b/chapter31/src/main/smp/sys/draw/Canvas.smp @@ -1,32 +1,76 @@ struct Canvas { - u32 width; - u32 height; - u32[] pixels; + u32 !width; + u32 !height; + u32[] !pixels; + // Layout coordinates are relative to the constructor's base size. + // A single float scale preserves circles and game geometry on resize. + u32 baseWidth, baseHeight; + f64 scale = 1.0; + int offsetX = 0, offsetY = 0; new Canvas = { u32 w, u32 h -> + if( w > sys.integer.MAX_I32 || h > sys.integer.MAX_I32 ) libc._exit(1); i64 count = w; count *= h; if( w <= 0 || h <= 0 || count > sys.integer.MAX_I32 ) libc._exit(1); width = w; height = h; + baseWidth = w; + baseHeight = h; pixels = new u32[count]; }; + // Ignore minimized windows. Return true only when a redraw is needed. + val resize = { u32 w, u32 h -> + if( w == 0 || h == 0 || (w == width && h == height) ) return false; + if( w > sys.integer.MAX_I32 || h > sys.integer.MAX_I32 ) libc._exit(1); + i64 count = w; count *= h; + if( count > sys.integer.MAX_I32 ) libc._exit(1); + // Reuse storage while dragging. Geometric growth bounds total allocation + // even in the current runtime, which does not yet collect old arrays. + if( count > pixels# ) { + i64 capacity = pixels#*2; + if( capacity < count ) capacity = count; + if( capacity > sys.integer.MAX_I32 ) capacity = sys.integer.MAX_I32; + pixels = new u32[capacity]; + } + width = w; height = h; + f64 sx = w*1.0/baseWidth, sy = h*1.0/baseHeight; + scale = sx < sy ? sx : sy; + offsetX = (w-baseWidth*scale)/2; + offsetY = (h-baseHeight*scale)/2; + return true; + }; + + // Inverse of the drawing transform. Margins are outside the layout; + // reject them before integer truncation can turn a small negative into 0. + val localX = { int x -> + if( x < offsetX || x >= offsetX+baseWidth*scale ) return -1; + int local = (x-offsetX)/scale; + return local; + }; + val localY = { int y -> + if( y < offsetY || y >= offsetY+baseHeight*scale ) return -1; + int local = (y-offsetY)/scale; + return local; + }; + val clear = { u32 color -> - for( int i = 0; i < pixels#; i++ ) pixels[i] = color; + i64 count = width; count *= height; + for( int i = 0; i < count; i++ ) pixels[i] = color; return self; }; val pixel = { i64 x, i64 y, u32 color -> - if( 0 <= x < width && 0 <= y < height ) pixels[y*width+x] = color; - return self; + return fillRect(x,y,1,1,color); }; // Integer coordinates, top-left origin. Rectangle extents are half-open. val fillRect = { i64 x, i64 y, i64 w, i64 h, u32 color -> if( w <= 0 || h <= 0 ) return self; - i64 right = x; right += w; - i64 bottom = y; bottom += h; + i64 right = offsetX+(x+w)*scale; + i64 bottom = offsetY+(y+h)*scale; + x = offsetX+x*scale; y = offsetY+y*scale; if( right <= 0 || bottom <= 0 || x >= width || y >= height ) return self; int x0 = x < 0 ? 0 : x, y0 = y < 0 ? 0 : y; int x1 = right > width ? width : right, y1 = bottom > height ? height : bottom; @@ -55,6 +99,10 @@ struct Canvas { }; val _circle = { i64 cx, i64 cy, int radius, int thickness, bool filled, u32 color -> if( radius < 0 || (!filled && thickness <= 0) ) return self; + cx = offsetX+cx*scale; cy = offsetY+cy*scale; + radius *= scale; + thickness *= scale; + if( !filled && thickness < 1 ) thickness = 1; i64 left = cx; left -= radius; i64 top = cy; top -= radius; i64 right = cx; right += radius; @@ -79,6 +127,10 @@ struct Canvas { // box is scanned. Floating distances avoid overflowing coordinate squares. val line = { i64 x0, i64 y0, i64 x1, i64 y1, i64 thickness, u32 color -> if( thickness <= 0 ) return self; + x0 = offsetX+x0*scale; y0 = offsetY+y0*scale; + x1 = offsetX+x1*scale; y1 = offsetY+y1*scale; + thickness *= scale; + if( thickness < 1 ) thickness = 1; i64 pad = thickness/2+1; i64 left = x0 < x1 ? x0 : x1; left -= pad; i64 top = y0 < y1 ? y0 : y1; top -= pad; diff --git a/chapter31/src/main/smp/sys/draw/README.md b/chapter31/src/main/smp/sys/draw/README.md new file mode 100644 index 00000000..7d3bf6c8 --- /dev/null +++ b/chapter31/src/main/smp/sys/draw/README.md @@ -0,0 +1,124 @@ +# Drawing in Simple + +[Chapter 31](../../../../../README.md#graphics-and-sound) introduces the library. +The implementation is in [Canvas.smp](Canvas.smp), [Button.smp](Button.smp), +and the [draw module](../draw.smp). + +`sys.draw` draws into an ordinary `u32[]`. It has no native dependencies and +does not open a window. `sys.gfx` presents the resulting pixels using the +optional [MiniFB backend](../gfx.md). + +```simple +val canvas = new sys.draw.Canvas(600,780); +u32 orange = 0xe47b57; +canvas.clear(sys.draw.WHITE); +canvas.fillRect(20,20,180,80,orange); +canvas.rect(20,20,180,80,3,sys.draw.BLACK); +canvas.circle(300,200,48,8,sys.draw.BLUE); +canvas.fillCircle(420,200,20,sys.draw.GREEN); +canvas.line(40,320,250,440,12,orange); +canvas.text(40,500,"YOUR TURN",4,sys.draw.BLACK); +// After sys.gfx.open succeeds: +sys.gfx.presentSize(canvas.pixels,canvas.width,canvas.height); +``` + +## Small raster API + +Coordinates start at the upper left; x increases rightward and y downward. +Drawing methods return the canvas for chaining. Everything is opaque RGB; +there is no blending, antialiasing, transform stack, or native drawing state. +Coordinates accept `i64` so ordinary widened arithmetic can be passed directly. +Circle radii and circle stroke widths are `int`. Use screen-sized coordinates, +extents, and stroke widths. + +| Operation | Behavior | +| --- | --- | +| `rgb(r,g,b)` | Clamp components to 0–255 and pack RGB. `BLACK`, `WHITE`, `RED`, `GREEN`, and `BLUE` are available too. | +| `new Canvas(width,height)` | Allocate a zero-filled pixel array. Dimensions must be positive and their product must fit a signed 32-bit index; invalid sizes exit with status 1. Allocation can still fail for lack of memory. | +| `resize(width,height)` | Fit the original layout into new drawable dimensions; return whether they changed. Ignore zero dimensions. | +| `localX(x)`, `localY(y)` | Convert drawable pixels to base coordinates for input; return -1 in the margins. | +| `clear(color)` | Fill the entire canvas. | +| `pixel(x,y,color)` | Set one pixel; ignore points outside the canvas. | +| `fillRect(x,y,w,h,color)` | Fill a half-open rectangle: x through x+w-1, y through y+h-1. | +| `rect(x,y,w,h,thickness,color)` | Draw an inward outline. A sufficiently wide outline fills the rectangle. | +| `fillCircle(cx,cy,radius,color)` | Fill a circle; radius zero draws its center pixel. | +| `circle(cx,cy,radius,thickness,color)` | Draw an inward circular outline. | +| `line(x0,y0,x1,y1,thickness,color)` | Draw a round-ended segment. A zero-length segment draws a round dot. Thickness is its geometric diameter, sampled at integer pixel centers. | +| `text(x,y,string,scale,color)` | Draw a 3×5 bitmap font, with one column between characters. Upper/lowercase ASCII letters, digits, spaces, and basic punctuation are supported. Newline advances six scaled pixels. Unknown characters use `?`. | + +Shapes clip to the canvas. Nonpositive rectangle extents, stroke widths, or +text scale do nothing; negative circle radii do nothing. Line and circle +coverage scans only the clipped bounding box, which is sufficient for small +turn-based games. This is a starting raster library rather than a fast animated +renderer. The pixel array remains available for direct drawing and inspection. + +The constructor sets the layout's `baseWidth` and `baseHeight`. Resizing uses +`scale = min(width/baseWidth, height/baseHeight)` in floating point and centers +the result with `offsetX` and `offsetY`. Sizes, offsets, glyph cells, and stroke +widths all use this transform; circles stay circular. Positive line and circle +strokes retain at least one drawable pixel. Existing drawing coordinates remain +in base units, while `width`, `height`, and direct pixel indexing use the actual +framebuffer dimensions. `clear` fills the whole framebuffer, including margins. +At very small sizes, details smaller than a pixel naturally disappear. + +Canvas reuses its pixel storage and grows its capacity geometrically when needed. +Only the first `width*height` elements are active; use `gfx.presentSize` after +resizing. This avoids allocating on every drag event, including repeated shrink +and grow cycles. Use `localX`/`localY` before button or game hit tests so drawing +and input share the same scale and centering. + +Packed colors use hexadecimal literals (`0xRRGGBB`); `rgb(r,g,b)` remains handy +for computed components. The font masks use leading-zero octal, with five +digits after the prefix: each digit is one three-pixel row, top to bottom. +For example, `A` is `025755`: rows `010`, `101`, `111`, `101`, `101`. +The font includes all printable ASCII punctuation except `@`, `&`, and `$`, +which use the question-mark fallback. Colons and slashes support clock and date +labels; quotes, brackets, arithmetic signs, and other small symbols fit in 3×5. + +## Button widget + +`new sys.draw.Button(x,y,width,height,label)` creates a rectangular software +button. It owns no window or native resources. Feed pointer coordinates and +the held mouse-button state to `update(x,y,down)` once per event-loop iteration. +It returns true once on release inside, provided the press began inside. +Dragging in from outside does not activate it; releasing outside cancels. + +`hovered` and `pressed` expose visual state. Set `enabled=false` to cancel a +pending press and disable activation; `label` can be changed at any time. +`contains(x,y)` uses half-open bounds. `draw(canvas,scale,foreground,background,active)` +paints the button and centers its 3x5 label when it fits. Colors belong to the +caller. Keyboard shortcuts belong to the application; this small widget has +no focus system. The [clock example](../../../../../docs/examples/Clock.smp) shows mouse activation +and a Space shortcut in the same single-threaded loop. + +## Graphical tic-tac-toe + +From `chapter31`: + +```sh +make run-graphical-tictactoe +``` + +Click an empty square or press **1–9**, numbered left-to-right, top-to-bottom. +You are X; the CPU is O. It wins when possible, blocks your immediate win, +then prefers the center, corners, and edges. The result stays visible with +the winning line highlighted. Press **R** or **Space** to start a new game, +or **Q**/**Escape** to quit. Restart is also available during a game. + +Held buttons and keys do not take repeated turns. Moving the pointer highlights +empty cells. The canvas is redrawn after a move, restart, hover change, or resize; +polling still processes window events and waits between polls. + +`make graphical-tictactoe` builds without opening a window or requiring +MiniFB. Its output is `build/examples/x86_64_v2_win64/TicTacToeGraphical.exe` +on Windows or `build/examples/x86_64_v2_SystemV/TicTacToeGraphical` on Linux. +Backend discovery and explicit overrides follow [the pixel-window instructions](../gfx.md). +Passing any argument performs a five-poll, self-closing smoke test. + +The original `make tictactoe` still builds the terminal game. +The graphical game also uses optional [background audio](../audio.md): a soft +boop for accepted moves, rising tones for a player win, and falling tones for +a CPU win. Bad input is silent. The run target builds/configures both backends. +`make test CLASS=DrawTest` checks raster pixels and complete game turns +without a display. `make tests_nographics` runs the ordinary suite with +the backend disabled. diff --git a/chapter31/src/main/smp/sys/gfx.md b/chapter31/src/main/smp/sys/gfx.md new file mode 100644 index 00000000..931d985f --- /dev/null +++ b/chapter31/src/main/smp/sys/gfx.md @@ -0,0 +1,154 @@ +# Optional graphics + +[Chapter 31](../../../../README.md#graphics-and-sound) introduces the library. +The Simple API is implemented in [gfx.smp](gfx.smp), with the window adapter in +[simple_minifb.c](../../c/simple_minifb.c). + +Simple owns the pixel array and drawing code. [MiniFB](https://github.com/emoon/minifb) +provides a window, input, and pixel presentation. The first interface is +`sys.gfx`: one resizable window, operated on the main thread. The +[Graphics example](../../../../docs/examples/Graphics.smp) draws a color gradient in Simple. +The [drawing library and graphical tic-tac-toe](draw/README.md) build on this pixel +interface. `make run-graphical-tictactoe` builds the optional backend and +opens the game; `make graphical-tictactoe` only builds its executable. +The game run target also builds optional [background audio](audio.md). + +## Default: no graphics dependency + +From `chapter31`, the usual `make release`, `make tests`, and `make tictactoe` +need no MiniFB, graphics headers, OpenGL, CMake, or running display. Nothing +downloads dependencies unless you explicitly request `make libs` or `make init` +(`make lib` remains a setup alias). Build and run targets never use the network. + +`make tests_nographics` runs the entire ordinary suite with +`SIMPLE_MINIFB=off`. This includes the missing-backend tests, which never open +windows. It excludes the interactive `run-graphics` target. + +The runtime contains a small loader using the OS dynamic-library facilities. +It does nothing until `sys.gfx.open`. Without an available backend, `open` +prints a diagnostic to stderr and returns `sys.gfx.ERROR` (-1). Programs can +return a nonzero status or fall back to text; the library does not terminate +the process. Non-graphics programs ignore even a broken graphics configuration. + +## Build the optional backend + +From `chapter31`: + +```sh +make libs # Once while online; fills the persistent lib/ cache. +make graphics graphics-example +make run-graphics +``` + +`libs` downloads the revision pinned in [graphics.mk](../../../../graphics.mk) into +ignored `lib/minifb-.tar.gz` and extracts it under `lib/`. +`graphics` builds only its C framebuffer backend from these local sources. Windows +uses the MinGW-w64 GCC compiler (`x86_64-w64-mingw32-gcc`) and GDI; the rest of +Simple still uses the existing Cygwin GCC. Linux uses GCC and X11 (`libx11-dev` +on Ubuntu), including XWayland on a Wayland desktop. OpenGL, the C++ callback +wrappers, and upstream example programs are omitted. Native Wayland and macOS +builds are not provided here yet. + +Outputs: + +| Platform | Backend | Example | +| --- | --- | --- | +| Windows | `build/release/x86_64_v2_win64/simple_minifb.dll` | `build/examples/x86_64_v2_win64/Graphics.exe` | +| Linux | `build/release/x86_64_v2_SystemV/libsimple_minifb.so` | `build/examples/x86_64_v2_SystemV/Graphics` | + +`MiniFB-LICENSE` is copied alongside the backend; include it when distributing +the library. MiniFB sources remain outside the tracked Simple sources. +The cache survives `make clean`. Editing a makefile or rebuilding a backend +does not fetch or check GitHub. Missing dependencies fail promptly with +instructions to run `make libs` while online. + +`graphics-example` alone builds the executable without requiring MiniFB. It +also demonstrates the diagnostic and exit status 1 when graphics is absent. +`run-graphics` builds both, sets the backend path, and opens a window. Close it +or release Escape to exit. Passing any argument to the executable makes it +close after five polling iterations, for a quick smoke test. + +To run directly from `chapter31` in PowerShell: + +```powershell +$env:SIMPLE_MINIFB = (Resolve-Path build/release/x86_64_v2_win64/simple_minifb.dll).Path +.\build\examples\x86_64_v2_win64\Graphics.exe +``` + +From Command Prompt (`cmd.exe`): + +```bat +set "SIMPLE_MINIFB=%CD%\build\release\x86_64_v2_win64\simple_minifb.dll" +.\build\examples\x86_64_v2_win64\Graphics.exe +``` + +From Bash (Cygwin, using the Windows build): + +```bash +export SIMPLE_MINIFB="$PWD/build/release/x86_64_v2_win64/simple_minifb.dll" +./build/examples/x86_64_v2_win64/Graphics.exe +``` + +For WSL, from the repository root: + +```sh +wsl -d Ubuntu-24.04 -- bash -lc 'cd chapter31 && make graphics graphics-example CLZDIR=build/classes-linux' +``` + +Inside WSL, set `SIMPLE_MINIFB` to the full path of the Linux `.so`, then run +the Linux example with a working X11 display. For an automated virtual display: + +```sh +SIMPLE_MINIFB="$PWD/build/release/x86_64_v2_SystemV/libsimple_minifb.so" \ + xvfb-run -a build/examples/x86_64_v2_SystemV/Graphics smoke +``` + +With no `SIMPLE_MINIFB` setting, the runtime searches beside the executable, +then its `../../release/` and `../release/` directories. These cover +the examples and test build layouts regardless of the current directory. +It also checks the current directory, `build/release/`, and +`chapter31/build/release/` relative to the current directory. Thus built +examples such as `Clock.exe` can be launched directly without configuration. + +`SIMPLE_MINIFB` overrides discovery; an invalid explicit path reports an error +without falling back. `SIMPLE_MINIFB=off` disables graphics for headless tests. +An absent, unloadable, or incompatible backend produces a diagnostic. +A backend that loads but cannot create a window also reports an error cleanly. + +## Initial interface + +| Operation | Meaning | +| --- | --- | +| `open(title,width,height)` | Open one window; returns `OK` or `ERROR`. | +| `present(pixels)` | Present a `u32[~]` of exactly the original `width*height` pixels, packed `0x00RRGGBB`. MiniFB stretches this buffer to the window. | +| `width()`, `height()` | Current drawable dimensions after the last event dispatch; zero when no window exists. | +| `presentSize(pixels,width,height)` | Present the first `width*height` elements of a buffer at an explicit resolution. Dimensions must be positive and fit the array. | +| `poll(wait)` | Process input; `true` waits up to 17ms, waking for input. | +| `wait(timeoutMs)` | Wait for input or timeout, then process events; 0 polls, -1 waits indefinitely. | +| `mouseX()`, `mouseY()` | Current mouse position, origin at upper left. | +| `button(LEFT)`, `key(code)` | Current pressed state; printable keys use uppercase ASCII. | +| `close()` | Release native window and pixel storage; safe to repeat. | + +`present`, `poll`, and `wait` return `OK` (0), `CLOSED` (1, normal close/Escape), or +`ERROR` (-1). Stop polling after either terminal result and call `close`. +The initial input API samples held state; it is not a queue of every transition. + +Waits may return early; values below -1 are errors. Recheck the monotonic +clock after waking. The [time library and animation example](time/README.md) combine +this wait with cooperative timer deadlines. Backend API version 3 adds +resizing and explicit framebuffer dimensions; rebuild older MiniFB adapters +with `make graphics` from the cached sources. + +For drawing at the new resolution, call `canvas.resize(gfx.width(),gfx.height())` +after processing events, redraw when it returns true, and use +`gfx.presentSize(canvas.pixels,canvas.width,canvas.height)`. Explicit buffer +dimensions remain valid if another resize arrives while presenting. Zero-sized +resize notifications are ignored by Canvas so minimizing retains the last layout. +Mouse coordinates are in drawable pixels; convert them with `canvas.localX` +and `canvas.localY` for hit testing in the [base layout](draw/README.md). + +MiniFB retains its last framebuffer for repaint events. The adapter copies the +Simple array into native-owned storage before presenting; it never retains a +Simple heap pointer. Framebuffer allocation, the copy, and window/input calls +are the only native work here. Drawing primitives and the games can be built +in Simple on top of this boundary. diff --git a/chapter31/src/main/smp/sys/gfx.smp b/chapter31/src/main/smp/sys/gfx.smp index ae203bd1..60505ac9 100644 --- a/chapter31/src/main/smp/sys/gfx.smp +++ b/chapter31/src/main/smp/sys/gfx.smp @@ -1,5 +1,6 @@ // Minimal pixel-window interface; drawing belongs in Simple. -// One fixed-size window, main thread only. Pixel format is 0x00RRGGBB. +// API and launch reference: gfx.md beside this file. +// One resizable window, main thread only. Pixel format is 0x00RRGGBB. // open/present/poll return OK, CLOSED (normal user close/Esc), or ERROR. int OK = 0; int CLOSED = 1; @@ -9,6 +10,9 @@ int ESCAPE = 256; { i64 u32 u32 -> i32 } simple_gfx_open = "C"; { i64 u32 -> i32 } simple_gfx_present = "C"; +{ i64 u32 u32 u32 -> i32 } simple_gfx_present_size = "C"; +{ u32 } simple_gfx_width = "C"; +{ u32 } simple_gfx_height = "C"; { i32 -> i32 } simple_gfx_poll = "C"; { i32 } simple_gfx_mouse_x = "C"; { i32 } simple_gfx_mouse_y = "C"; @@ -31,6 +35,19 @@ val present = { u32[~] pixels -> simple_gfx_present(ptr,pixels#); }; +// Drawable size after the last event dispatch; zero when closed. +val width = { -> simple_gfx_width(); }; +val height = { -> simple_gfx_height(); }; +// Explicit dimensions keep a resize arriving during presentation harmless. +val presentSize = { u32[~] pixels, u32 width, u32 height -> + if( width == 0 || height == 0 || width > pixels# || height > pixels# ) return ERROR; + i64 count = width; count *= height; + if( count > pixels# ) return ERROR; + i64 ptr = pixels; + u32 size = count; + simple_gfx_present_size(ptr,size,width,height); +}; + // wait=true waits up to 17ms, waking early for input to avoid a busy loop. val poll = { bool wait -> simple_gfx_poll(wait); }; val mouseX = { -> simple_gfx_mouse_x(); }; diff --git a/chapter31/src/main/smp/sys/math.smp b/chapter31/src/main/smp/sys/math.smp index a5e1887c..33bb0e5f 100644 --- a/chapter31/src/main/smp/sys/math.smp +++ b/chapter31/src/main/smp/sys/math.smp @@ -2,7 +2,19 @@ val PI = 3.141592653589793; val E = 2.718281828459045; +// Native libm functions, all f64 -> f64. sin/cos take radians; exp is e^x, +// log is the natural logarithm, and sqrt is the nonnegative square root. +// These are ordinary C calls: results and domain/range errors (including +// errno) follow the host libm. They are not folded or treated as pure intrinsics. +// The standard linker already includes -lm. +{ f64 -> f64 } sin = "C"; +{ f64 -> f64 } cos = "C"; +{ f64 -> f64 } exp = "C"; +{ f64 -> f64 } log = "C"; +{ f64 -> f64 } sqrt = "C"; + // Fixed-semantics C bindings recognized by the compiler's intrinsic inliner. +// See chapter31/README.md, "Math support and intrinsics", for the compiler contract. // These preserve all 64 bits, including signed zero and NaN payloads. // They are NOT numeric conversions (ordinary typed assignments still are). { f64 -> i64 } simple_f64_bits = "C"; diff --git a/chapter31/src/main/smp/sys/text.smp b/chapter31/src/main/smp/sys/text.smp index 43698f22..77dc2190 100644 --- a/chapter31/src/main/smp/sys/text.smp +++ b/chapter31/src/main/smp/sys/text.smp @@ -43,7 +43,7 @@ val integer = { !aryu8 b, i64 value, i64 spec, i64 width, i64 precision -> if( n == 0 && precision != 0 ) digits[count++] = '0'; while( n != 0 ) { i64 q = 0, r = 0; - if( signed ) { q = n/base; r = q*base-n; } + if( signed ) { q = n/base; r = -(n%base); } else { // Unsigned division without a u64 type. Halving first makes // the dividend nonnegative; the remainder needs at most one fix. diff --git a/chapter31/src/main/smp/sys/time.smp b/chapter31/src/main/smp/sys/time.smp index a3e9b3a2..27378ffe 100644 --- a/chapter31/src/main/smp/sys/time.smp +++ b/chapter31/src/main/smp/sys/time.smp @@ -1,4 +1,5 @@ // Time utilities; get the current time (both nanos and millis), sleep, time zones. +// API, formatting, and timer reference: time/README.md. // Instants: bare i64 UTC Unix-epoch milliseconds. Durations: i64 milliseconds. // Monotonic readings are a separate clock domain, for deadlines/elapsed time. @@ -61,8 +62,7 @@ val remaining = { i64 deadline_ms, i64 current_ms -> return deadline_ms-current_ms; }; -val _mod = { i64 n, i64 unit -> n-n/unit*unit; }; -val leap = { int year -> _mod(year,4) == 0 && (_mod(year,100) != 0 || _mod(year,400) == 0); }; +val leap = { int year -> year%4 == 0 && (year%100 != 0 || year%400 == 0); }; val monthDays = { int year, int month -> if( month < 1 || month > 12 ) return 0; return month == 2 ? (leap(year) ? 29 : 28) : @@ -72,7 +72,7 @@ val monthDays = { int year, int month -> // Gregorian civil dates, expressed using 400-year eras; no per-year loops. val _days = { i64 year, i64 month, i64 day -> year -= month <= 2 ? 1 : 0; - i64 era = year/400, y = year-era*400; + i64 era = year/400, y = year%400; i64 mp = month+(month > 2 ? -3 : 9); return era*_DAYS_PER_ERA+y*365+y/4-y/100+(153*mp+2)/5+day-1-_MARCH_EPOCH_DAYS; }; @@ -91,17 +91,17 @@ val makeUTC = { int year, int month, int day, int hour, int minute, int second, val utc = { i64 instant -> val d = DateTime.empty(); if( instant < MIN || instant > MAX ) return d; - i64 day = instant/DAY, rest = _mod(instant,DAY); + i64 day = instant/DAY, rest = instant%DAY; if( rest < 0 ) { rest += DAY; day--; } - i64 z = day+_MARCH_EPOCH_DAYS, era = z/_DAYS_PER_ERA, doe = z-era*_DAYS_PER_ERA; + i64 z = day+_MARCH_EPOCH_DAYS, era = z/_DAYS_PER_ERA, doe = z%_DAYS_PER_ERA; i64 y = (doe-doe/(_DAYS_PER_4_YEARS-1)+doe/_DAYS_PER_CENTURY-doe/(_DAYS_PER_ERA-1))/365; i64 doy = doe-(365*y+y/4-y/100), mp = (5*doy+2)/153; d.day = doy-(153*mp+2)/5+1; d.month = mp+(mp < 10 ? 3 : -9); d.year = y+era*400+(d.month <= 2 ? 1 : 0); - d.hour = rest/HOUR; d.minute = _mod(rest/MINUTE,60); - d.second = _mod(rest/SECOND,60); d.millisecond = _mod(rest,SECOND); - d.weekday = _mod(day+4,7); + d.hour = rest/HOUR; d.minute = rest/MINUTE%60; + d.second = rest/SECOND%60; d.millisecond = rest%SECOND; + d.weekday = (day+4)%7; if( d.weekday < 0 ) d.weekday += 7; return d; }; @@ -136,13 +136,13 @@ val _format = { i64 instant, int style, bool localZone -> if( d.year == 0 || style < 0 || style > 5 || style == 3 ) return ""; val b = new aryu8(); if( style == 4 ) { - _digits(b,d.day,2).add('/'); _digits(b,d.month,2).add('/'); _digits(b,_mod(d.year,100),2); + _digits(b,d.day,2).add('/'); _digits(b,d.month,2).add('/'); _digits(b,d.year%100,2); } else { if( style == 0 ) { _digits(b,d.year,4).add('-'); _digits(b,d.month,2).add('-'); _digits(b,d.day,2).add('T'); } int hour = d.hour; - if( style == 1 ) { hour = _mod(hour,12); if( hour == 0 ) hour = 12; } + if( style == 1 ) { hour = hour%12; if( hour == 0 ) hour = 12; } _digits(b,hour,style == 1 ? 1 : 2).add(':'); _digits(b,d.minute,2); if( style == 0 || style == 5 ) { b.add(':'); _digits(b,d.second,2); } if( style == 1 ) b.addAry(d.hour < 12 ? "am" : "pm"); @@ -153,8 +153,8 @@ val _format = { i64 instant, int style, bool localZone -> i64 offset = d.offsetSeconds; b.add(offset < 0 ? '-' : '+'); if( offset < 0 ) offset = -offset; - _digits(b,offset/3600,2).add(':'); _digits(b,_mod(offset/60,60),2); - if( _mod(offset,60) != 0 ) { b.add(':'); _digits(b,_mod(offset,60),2); } + _digits(b,offset/3600,2).add(':'); _digits(b,offset/60%60,2); + if( offset%60 != 0 ) { b.add(':'); _digits(b,offset%60,2); } } } } @@ -166,7 +166,7 @@ val elapsed = { i64 ms -> // Nonpositive arithmetic handles the minimum i64 without negating it. if( ms < 0 ) b.add('-'); else ms = -ms; _digits(b,-(ms/MINUTE),2).add(':'); - _digits(b,-_mod(ms/SECOND,60),2).add('.'); _digits(b,-_mod(ms,SECOND),3); + _digits(b,-(ms/SECOND%60),2).add('.'); _digits(b,-(ms%SECOND),3); return text.end(b); }; val format = { i64 instant, int style -> diff --git a/chapter31/src/main/smp/sys/time/README.md b/chapter31/src/main/smp/sys/time/README.md new file mode 100644 index 00000000..baa920cb --- /dev/null +++ b/chapter31/src/main/smp/sys/time/README.md @@ -0,0 +1,133 @@ +# Time and single-threaded animation + +[Chapter 31](../../../../../README.md#time-library) introduces the library. +The implementation is in [time.smp](../time.smp), [DateTime.smp](DateTime.smp), +and [Timers.smp](Timers.smp). + +`sys.time` uses bare `i64` values: absolute instants are milliseconds since +the Unix epoch in UTC; durations are milliseconds. Monotonic readings belong +to a separate clock domain. Never subtract a wall-clock reading from a +monotonic deadline. + +## Clocks and waits + +| Call | Result | +| --- | --- | +| `time.now()` | Unix-epoch milliseconds; may jump when the system clock changes. | +| `time.monotonic()` | Monotonic milliseconds for elapsed time and deadlines. | +| `time.nanoTime()` | Monotonic nanoseconds, with the clock's available resolution. | +| `time.sleep(duration_ms)` | Sleep for a nonnegative duration. | +| `time.sleepUntil(deadline_ms)` | Wait for a monotonic millisecond deadline; returns immediately if past. | +| `time.remaining(deadline_ms, current_ms)` | Nonnegative difference, saturating on overflow. | + +Clock errors return `-1`; sleeps return zero on success or `-1` on error, +with `sys.libc.errno()` available. Interrupted sleeps resume rather than +returning early. Wakeup times are approximate, and these calls do not wake a +suspended laptop. Sleeping blocks the one Simple execution thread; use +`gfx.wait` when window input must remain responsive. + +`seconds(n)`, `minutes(n)`, `hours(n)`, and `days(n)` convert signed counts +to milliseconds. `toSeconds(ms)`, `toMinutes(ms)`, `toHours(ms)`, and +`toDays(ms)` truncate toward zero. A duration day is exactly 24 hours, +independent of daylight saving. `toNanos(ms)` and `fromNanos(ns)` convert +between millisecond and nanosecond units. Multiplication overflow returns +`-1`. Constants `SECOND`, `MINUTE`, `HOUR`, and `DAY` are also available, +defined as `1000`, `60*SECOND`, `60*MINUTE`, and `24*HOUR` respectively. +`NANOS_PER_MS` is `1000*1000`. Overflow checks use the shared +`sys.integer.MIN_I64` and `MAX_I64` bounds; `MAX_I32` and `MAX_U32` in that +module also describe the library's array and timer-ID limits. + +## String interpolation + +Time formatting is built into the existing string interpolation syntax: + +| Format | Example | Named style | +| --- | --- | --- | +| `%t(instant)` or `%tF(instant)` | `2026-11-12T00:34:05.123Z` | `time.ISO` | +| `%tr(instant)` | `12:34am` | `time.CLOCK12` | +| `%tR(instant)` | `00:34` | `time.CLOCK24` | +| `%tT(instant)` | `00:34:05` | `time.CLOCK24_SECONDS` | +| `%tD(instant)` | `12/11/26` | `time.DATE` | +| `%tM(duration)` | `02:03.456` | `time.ELAPSED` | + +For example, `"UTC %tR(sys.time.now())"`. Width and left alignment work as +for strings: `%30t(instant)` and `%-30t(instant)`. Precision and numeric flags +are rejected. `%tM` formats a duration, with total minutes rather than wrapping +at an hour; negative durations keep their sign. + +Interpolation uses UTC, making its output stable across machines. +`time.format(instant, style)` is the equivalent library call; +`time.formatLocal(instant, style)` uses the system's local zone. Local ISO +output includes a numeric offset instead of `Z` when nonzero, retaining +offset seconds for historical zones. Invalid calendar values/styles produce +``. The ISO form retains all millisecond bits within the supported +calendar range; short formats intentionally omit information. + +## Calendar values and absolute parsing + +`time.utc(instant)` and `time.local(instant)` return a `DateTime` with fields +`year`, `month`, `day`, `hour`, `minute`, `second`, `millisecond`, `weekday` +(Sunday = 0), `offsetSeconds` (east of UTC), and `daylight`. A zero year means +conversion failed. `time.zoneName(instant)` returns the local abbreviation or +an empty string on error. Local conversion uses the operating system's zone +rules, including DST at that instant; no time-zone database is downloaded. + +`time.makeUTC(year, month, day, hour, minute, second, millisecond)` validates +and constructs an instant, returning `-1` on invalid fields. `time.valid(...)`, +`time.leap(year)`, and `time.monthDays(year, month)` support calendar checks. +Calendar conversion supports Gregorian years 1 through 9999, bounded by +`time.MIN` and `time.MAX`, and rejects leap seconds. + +`time.parse(text)` accepts strict absolute ISO text: +`YYYY-MM-DDTHH:mm:ss[.SSS]Z` or the same with an explicit `+HH:MM`/`-HH:MM` +offset (optionally with `:SS`). Fractions have exactly three digits. No relative +time parsing, implicit local zone, locale-dependent parsing, or named-zone +conversion is provided. Offsets must have hours 00–23 and minutes/seconds 00–59. +Invalid text or an out-of-range result returns `-1`. By design, this sentinel +is indistinguishable from the valid instant `1969-12-31T23:59:59.999Z`; +formatting and calendar conversion still support that instant. + +## Cooperative timers + +Create `val timers = new sys.time.Timers();` on the game thread: + +Timer IDs are `u32`, with `0` reserved for registration failure or no timer due. +Deadlines, delays, and periods remain `i64` milliseconds; their parameter, +field, and local names end in `_ms` to distinguish them from IDs. + +| Operation | Meaning | +| --- | --- | +| `after(delay_ms)` | Register a one-shot timer; return its positive `u32` ID, or `0`. | +| `every(period_ms)` | Register a repeating timer; period must be positive. Returns a `u32` ID, or `0`. | +| `afterAt(current_ms, delay_ms)`, `everyAt(current_ms, period_ms)` | Supply a monotonic reading explicitly, useful for deterministic tests. | +| `cancel(id)` | Remove a timer; return whether it was present. | +| `nextDeadline()` | Earliest monotonic deadline, or `-1` if empty. | +| `poll(current_ms)` | Return the next due `u32` ID, or `0` if none. | + +Poll repeatedly to drain due timers. Deadlines order delivery, then registration +ID breaks ties. Repeating timers advance from their previous deadline, skipping +missed ticks to the first future deadline rather than drifting or replaying a +backlog. Deadline overflow rejects registration or cancels a repeating timer. +IDs are never reused within a collection; registration fails once all nonzero +`u32` IDs have been issued. +There are no callbacks or timer threads: the caller handles each returned ID. + +`gfx.wait(timeout_ms)` processes events after waiting for input or a timeout: +zero polls, `-1` waits indefinitely, values below `-1` fail. It returns the same +`OK`, `CLOSED`, or `ERROR` statuses as `gfx.poll`, and may wake early. Re-read the +monotonic clock after each wake. This allows one thread to handle timers, +input, simulation, and drawing without busy waiting. + +The [digital and analog clock example](../../../../../docs/examples/Clock.smp) combines these pieces. From +the repository root, with graphics dependencies already cached: + +```sh +make -C chapter31 clock-example # Build without opening a window. +make -C chapter31 run-clock # Build the backend and run. +``` + +Click the button or press Space to switch between green seven-segment digits +and an analog dial with smoothly moving hands. Both display system-local time; +Q/Escape exits. Passing any argument directly to the executable closes it after +ten frames, switching faces halfway through. Hands are computed from the current +time, so delayed frames do not create a simulation catch-up backlog. diff --git a/chapter31/src/test/java/com/seaofnodes/simple/ArithNodeTest.java b/chapter31/src/test/java/com/seaofnodes/simple/ArithNodeTest.java index b29c9706..2299bd17 100644 --- a/chapter31/src/test/java/com/seaofnodes/simple/ArithNodeTest.java +++ b/chapter31/src/test/java/com/seaofnodes/simple/ArithNodeTest.java @@ -85,6 +85,7 @@ public class ArithNodeTest { ops.add(new SubNode(lhs,rhs,mode)); ops.add(new MulNode(lhs,rhs,mode)); ops.add(new DivNode(lhs,rhs,mode)); + ops.add(new ModNode(lhs,rhs,mode)); } ops.add(new AndNode(null,lhs,rhs)); ops.add(new OrNode(null,lhs,rhs)); diff --git a/chapter31/src/test/java/com/seaofnodes/simple/BreakoutTest.java b/chapter31/src/test/java/com/seaofnodes/simple/BreakoutTest.java index 7f3e56d4..f374d397 100644 --- a/chapter31/src/test/java/com/seaofnodes/simple/BreakoutTest.java +++ b/chapter31/src/test/java/com/seaofnodes/simple/BreakoutTest.java @@ -191,7 +191,7 @@ public class BreakoutTest { g._serve(); // Drive through every brick's front, bottom row first. for( int i=COLS*ROWS-1; i>=0; i-- ) { - g.x=LEFT+20.0+(i-i/COLS*COLS)*BRICK_DX; + g.x=LEFT+20.0+(i%COLS)*BRICK_DX; g.y=BRICK_TOP+1.0+(i/COLS)*BRICK_DY+BRICK_H+RADIUS; g.dx=0.0; g.dy=-1.0; g._tick(0); diff --git a/chapter31/src/test/java/com/seaofnodes/simple/DrawTest.java b/chapter31/src/test/java/com/seaofnodes/simple/DrawTest.java index 1ca161cf..2af3b03e 100644 --- a/chapter31/src/test/java/com/seaofnodes/simple/DrawTest.java +++ b/chapter31/src/test/java/com/seaofnodes/simple/DrawTest.java @@ -3,19 +3,51 @@ package com.seaofnodes.simple; import java.nio.file.Files; import java.nio.file.Path; import org.junit.Test; -import com.seaofnodes.simple.codegen.CodeGen; -import com.seaofnodes.simple.type.TypeInteger; -import com.seaofnodes.simple.util.Ary; -import static org.junit.Assert.*; // Native raster and game checks; no backend or display is needed. public class DrawTest { + @Test public void resizedLayoutAndInput() throws Exception { + String game=Files.readString(Path.of("docs/examples/TicTacToeGraphical.smp")) + .replace("val main =","val _windowMain ="); + TestC.runSYS(game+""" + val main={ -> + val c=new sys.draw.Canvas(600,780); + val original=c.pixels; + val board=new u8[9]; _reset(board); + // Half size with horizontal margins: board remains square. + if( !c.resize(500,390) || c.scale!=0.5 || c.offsetX!=100 || c.offsetY!=0 ) return 1; + if( c.pixels!=original ) return 13; + _draw(c,board,4); + if( c.pixels[84*500+124]!=0x35535a || c.pixels[0]!=0x142e36 ) return 2; + if( _square(c.localX(250),c.localY(210))!=4 || c.localX(99)!=-1 ) return 3; + if( c.localX(400)!=-1 || c.localY(390)!=-1 ) return 4; + // Noninteger scale, taller aspect ratio, and scaled button hit box. + val b=new sys.draw.Button(48,168,168,168,"GO"); + if( !c.resize(750,1100) || c.scale!=1.25 || c.offsetY!=62 ) return 5; + val grown=c.pixels; + if( b.update(c.localX(100),c.localY(300),true) ) return 6; + if( !b.update(c.localX(100),c.localY(300),false) ) return 7; + c.clear(0).fillCircle(300,400,40,9).text(48,34,"GO",3,7); + if( c.pixels[562*750+425]!=9 || c.pixels[612*750+375]!=9 ) return 8; + if( c.pixels[562*750+426]!=0 || c.pixels[613*750+375]!=0 ) return 9; + // Minimize and repeated sizes retain the last usable buffer. + if( c.resize(0,0) || c.resize(750,1100) || c.width!=750 ) return 10; + if( !c.resize(1,1) ) return 11; + _draw(c,board,4); + if( !c.resize(600,780) || c.scale!=1.0 || c.offsetX!=0 || c.offsetY!=0 ) return 12; + if( c.pixels!=grown ) return 14; + return 0; + }; + ""","drawResize","",-1); + } + @Test public void nativeClockCoordinates() throws Exception { String clock=Files.readString(Path.of("docs/examples/Clock.smp")) .replace("val main =","val _windowMain ="); StringBuilder source=new StringBuilder(clock+""" val _check_noInline={ f64 turn, int expectedX, int expectedY -> - int x=360+_sin(turn)*128, y=232-_sin(turn+0.25)*128; + f64 angle=turn*2*sys.math.PI; + int x=360+sys.math.sin(angle)*128, y=232-sys.math.cos(angle)*128; if( xexpectedX+1 || yexpectedY+1 ) { sys.io.p("turn %f(turn): %(x),%(y) expected %(expectedX),%(expectedY)\\n"); return 1; @@ -26,7 +58,7 @@ public class DrawTest { """); for(int i=0;i<=60;i++) { double turn=i/60.0; - int x=(int)(360+clockSine(turn)*128), y=(int)(232-clockSine(turn+0.25)*128); + int x=(int)(360+Math.sin(turn*2*Math.PI)*128), y=(int)(232-Math.cos(turn*2*Math.PI)*128); source.append("if(_check_noInline(").append(turn).append(',').append(x).append(',').append(y) .append(")!=0) return 1;"); } @@ -34,14 +66,6 @@ public class DrawTest { TestC.runSYS(source.toString(),"clockCoordinates","",-1); } - private static double clockSine(double turn) { - turn-=(long)turn; - boolean negative=turn>0.5; - double x=(negative ? turn-0.5 : turn)*6.283185307179586; - double product=x*(3.141592653589793-x); - return (negative ? -16.0 : 16.0)*product/(49.34802200544679-4*product); - } - @Test public void nativeAnalogSweep() throws Exception { String clock=Files.readString(Path.of("docs/examples/Clock.smp")) .replace("val main =","val _windowMain ="); @@ -69,7 +93,7 @@ public class DrawTest { """); for(int millis:new int[]{0,500,7500,15000,30000,45000,59500}) { double turn=millis/60000.0; - int x=(int)(360+clockSine(turn)*128), y=(int)(232-clockSine(turn+0.25)*128); + int x=(int)(360+Math.sin(turn*2*Math.PI)*128), y=(int)(232-Math.cos(turn*2*Math.PI)*128); source.append("if(_renderCheck_noInline(").append(millis/1000).append(',').append(millis%1000) .append(',').append(x).append(',').append(y).append(")!=0) return 1;"); } @@ -103,7 +127,7 @@ public class DrawTest { @Test public void clockFacesWithoutWindow() throws Exception { String clock=Files.readString(Path.of("docs/examples/Clock.smp")) .replace("val main =","val _windowMain ="); - CodeGen code=new CodeGen(null,null,new Ary<>(new String[]{TestC.RELEASE_SYS_DIR}),"ClockRaster",clock+""" + TestC.runSYS(clock+""" val main={ -> val c=new sys.draw.Canvas(720,540); _digit(c,10,10,8); @@ -114,12 +138,9 @@ public class DrawTest { if( c.pixels[214*720+254]!=GREEN || c.pixels[262*720+470]!=GREEN ) return 3; c.clear(BACKGROUND); _analog(c,3,0,0,0); if( c.pixels[232*720+430]!=GREEN || c.pixels[160*720+360]!=0xc3ffcb || c.pixels[232*720+360]!=GREEN ) return 4; - if( _sin(0.25)<0.999 || _sin(0.75)>-0.999 || _sin(1.0)!=0.0 ) return 5; return 0; }; - return main(); - """,126L,true,TypeInteger.BOT).driver(CodeGen.Phase.TypeCheck); - assertEquals("0",Eval2.eval(code,0,3000000)); + ""","clockRaster","",-1); } @Test public void rectanglesAndColors() throws Exception { diff --git a/chapter31/src/test/java/com/seaofnodes/simple/Eval2.java b/chapter31/src/test/java/com/seaofnodes/simple/Eval2.java index eef05f93..d6d97ef1 100644 --- a/chapter31/src/test/java/com/seaofnodes/simple/Eval2.java +++ b/chapter31/src/test/java/com/seaofnodes/simple/Eval2.java @@ -313,6 +313,9 @@ public abstract class Eval2 { case DivNode div -> div.mode()==1 ? (Object)(x(div.in(2))==0 ? 0L : x(div.in(1)) / x(div.in(2))) : (Object)((d(div.in(2))==0 ? 0D : d(div.in(1))) / d(div.in(2))); + case ModNode mod -> mod.mode()==1 + ? (Object)(x(mod.in(2))==0 ? 0L : x(mod.in(1)) % x(mod.in(2))) + : (Object)(d(mod.in(1)) % d(mod.in(2))); case EscapeNode esc -> esc(esc); case FunPtrNode fptr -> con(fptr._con); case LoadNode ld -> load(ld); diff --git a/chapter31/src/test/java/com/seaofnodes/simple/GraphicsTest.java b/chapter31/src/test/java/com/seaofnodes/simple/GraphicsTest.java index 110a6a38..3b4b9e31 100644 --- a/chapter31/src/test/java/com/seaofnodes/simple/GraphicsTest.java +++ b/chapter31/src/test/java/com/seaofnodes/simple/GraphicsTest.java @@ -32,6 +32,7 @@ public class GraphicsTest { private static String run(String exe, String backend, int exit, Path cwd) throws Exception { ProcessBuilder pb = new ProcessBuilder(Path.of(exe).toAbsolutePath().toString()).redirectErrorStream(true); + pb.environment().put("SIMPLE_MINIAUDIO","off"); if (cwd!=null) pb.directory(cwd.toFile()); if( backend == null ) pb.environment().remove("SIMPLE_MINIFB"); else pb.environment().put("SIMPLE_MINIFB",backend); @@ -68,9 +69,12 @@ public class GraphicsTest { static int32_t poll_events(int32_t n) { return 0; } static int32_t position(void) { return 0; } static int32_t wait_events(int64_t n) { return 0; } + static uint32_t size(void) { return 0; } + static int32_t present_size(const uint32_t *p,uint32_t n,uint32_t w,uint32_t h) { return 0; } static void close_window(void) {} static const struct simple_graphics_api api={SIMPLE_GRAPHICS_VERSION, - open_window,present,poll_events,position,position,poll_events,poll_events,close_window,wait_events}; + open_window,present,poll_events,position,position,poll_events,poll_events,close_window,wait_events, + size,size,present_size}; const struct simple_graphics_api *simple_minifb_api(void) { return &api; } """); Path mock=root.resolve(name); @@ -150,9 +154,15 @@ public class GraphicsTest { (k=='R' && (frames==8 || frames==9)); } static int32_t wait_events(int64_t ms) { usleep(ms*1000); return 0; } + static uint32_t width(void) { return 1008; } + static uint32_t height(void) { return 760; } + static int32_t present_size(const uint32_t *p,uint32_t n,uint32_t w,uint32_t h) { + return w==1008 && h==760 ? present(p,n) : -1; + } static void close_window(void) {} static const struct simple_graphics_api api={SIMPLE_GRAPHICS_VERSION, - open_window,present,poll_events,mouse_x,mouse_y,poll_events,key,close_window,wait_events}; + open_window,present,poll_events,mouse_x,mouse_y,poll_events,key,close_window,wait_events, + width,height,present_size}; const struct simple_graphics_api *simple_minifb_api(void) { return &api; } """); TestC.exec(30,"gcc","-shared","-fPIC","-Isrc/main/c",source.toString(),"-o",library.toString()); @@ -174,6 +184,50 @@ public class GraphicsTest { assertTrue(output,output.contains("cannot load MiniFB backend")); } + @Test public void demosResizeWithoutDisplay() throws Exception { + Path source=Path.of("build/objs/graphics_resize.c"); + Path library=Path.of("build/objs/graphics_resize"+(TestC.OS.startsWith("Windows") ? ".dll" : ".so")); + Files.writeString(source,""" + #include "simple_graphics.h" + #include + #include + static unsigned step, seen, base_w, base_h; + static uint32_t width(void) { + return step==1 ? base_w/2 : step==2 ? base_w+123 : step==3 ? 1 : step==4 ? 0 : base_w; + } + static uint32_t height(void) { + return step==1 ? base_h/2 : step==2 ? base_h/2+17 : step==3 ? 1 : step==4 ? 0 : base_h; + } + static int32_t open_window(const char *s,uint32_t w,uint32_t h) { + base_w=w; base_h=h; return 0; + } + static int32_t present_size(const uint32_t *p,uint32_t n,uint32_t w,uint32_t h) { + if(!p || n!=(uint64_t)w*h || (step!=4 && (w!=width() || h!=height()))) return -1; + seen |= 1u< x==x && x-y<1e-12 && y-x<1e-12; }; + val main={ -> + val angles=new f64[~]{-sys.math.PI/2,0.0,sys.math.PI/6,sys.math.PI/2}; + val sines=new f64[~]{-1.0,0.0,0.5,1.0}; + val cosines=new f64[~]{0.0,1.0,0.8660254037844386,0.0}; + for(int i=0;i x!=x; }; + val main={ -> + f64 inf=sys.math.f64FromBits(0x7ff0000000000000); + f64 qnan=sys.math.f64FromBits(0x7ff8000000000001); + if(!nan(sys.math.sin(inf)) || !nan(sys.math.cos(inf))) return 1; + if(!nan(sys.math.log(-1.0)) || !nan(sys.math.sqrt(-1.0))) return 2; + if(sys.math.log(0.0)!=-inf || sys.math.log(inf)!=inf) return 3; + if(sys.math.exp(inf)!=inf || sys.math.exp(-inf)!=0.0) return 4; + if(sys.math.sqrt(inf)!=inf) return 5; + if(sys.math.f64Bits(sys.math.sin(-0.0))!=sys.integer.MIN_I64) return 6; + if(sys.math.f64Bits(sys.math.sqrt(-0.0))!=sys.integer.MIN_I64) return 7; + if(sys.math.cos(-0.0)!=1.0) return 8; + if(!nan(sys.math.sin(qnan)) || !nan(sys.math.cos(qnan))) return 9; + if(!nan(sys.math.exp(qnan)) || !nan(sys.math.log(qnan)) || + !nan(sys.math.sqrt(qnan))) return 10; + if(sys.math.exp(1000.0)!=inf || sys.math.exp(-1000.0)!=0.0) return 11; + return 0; + }; + ""","mathSpecial","",-1); + } + + @Test public void indirectBindings() throws Exception { + TestC.runSYS(""" + val apply_noInline={ { f64 -> f64 } f, f64 x -> f(x); }; + val main={ -> + if(apply_noInline(sys.math.sin,0.0)!=0.0) return 1; + if(apply_noInline(sys.math.cos,0.0)!=1.0) return 2; + if(apply_noInline(sys.math.exp,0.0)!=1.0) return 3; + if(apply_noInline(sys.math.log,1.0)!=0.0) return 4; + if(apply_noInline(sys.math.sqrt,9.0)!=3.0) return 5; + return 0; + }; + ""","mathIndirect","",-1); + } + + @Test public void allBackends() { + // Load just math from source so each backend selects its own C ABI. + String source=""" + f64 x=arg; + return math.sin(x)+math.cos(x)+math.exp(x)+ + math.log(x)+math.sqrt(x); + """; + for(String cpu:new String[]{"x86_64_v2","arm","riscv"}) + new CheckedCodeGen("src/main/smp/sys",null,null,"MathCalls",source,126,true,TypeInteger.BOT) + .driver(CodeGen.Phase.Encoding,cpu,"SystemV"); + } +} diff --git a/chapter31/src/test/java/com/seaofnodes/simple/ModTest.java b/chapter31/src/test/java/com/seaofnodes/simple/ModTest.java new file mode 100644 index 00000000..7f79599d --- /dev/null +++ b/chapter31/src/test/java/com/seaofnodes/simple/ModTest.java @@ -0,0 +1,201 @@ +package com.seaofnodes.simple; + +import com.seaofnodes.simple.codegen.CodeGen; +import com.seaofnodes.simple.codegen.RegAllocTestSupport.CheckedCodeGen; +import com.seaofnodes.simple.node.*; +import com.seaofnodes.isa.eval.EvalArm64; +import com.seaofnodes.isa.eval.EvalRisc5; +import com.seaofnodes.simple.type.TypeInteger; +import com.seaofnodes.simple.util.Ary; +import java.nio.file.Files; +import java.nio.file.Path; +import org.junit.Test; +import static org.junit.Assert.*; + +public class ModTest { + private static String literal(long x) { + return x==Long.MIN_VALUE ? "(-9223372036854775807-1)" : Long.toString(x); + } + @Test public void integers() { + long[] values={Long.MIN_VALUE,-17,-1,0,1,17,Long.MAX_VALUE}; + long[] divisors={Long.MIN_VALUE,-5,-1,0,1,5,Long.MAX_VALUE}; + for( long y : divisors ) { + for( long x : values ) { + CodeGen code=new CodeGen("return arg%"+literal(y)+";"); + String expected=Long.toString(y==0 ? 0 : x%y); + try { + assertEquals(x+"%"+y,expected,Eval2.eval(code,x)); + assertEquals(expected,Eval2.eval(new CodeGen("return "+literal(x)+"%"+literal(y)+";"),0)); + } catch(Throwable e) { throw new AssertionError(x+"%"+y,e); } + } + } + } + @Test public void precedenceAndIdentifiers() { + assertEquals("6",Eval2.eval(new CodeGen("return 20%6*3;"),0)); + assertEquals("2",Eval2.eval(new CodeGen("return 20/3%4;"),0)); + assertEquals("21",Eval2.eval(new CodeGen("int mod=20; return mod+7%3;"),0)); + } + @Test public void compoundAssignment() { + assertEquals("-2",Eval2.eval(new CodeGen("int x=arg; x %= 5; return x;"),-17)); + assertEquals("0",Eval2.eval(new CodeGen("int x=17; x %= arg; return x;"),0)); + assertEquals("1.5",Eval2.eval(new CodeGen("f64 x=7.5; x %= 2; return x;"),0)); + assertEquals("21",Eval2.eval(new CodeGen(""" + val a=new int[1]; a[0]=17; + int i=0; a[i++] %= 5; + return a[0]*10+i; + """),0)); + } + @Test public void floats() { + for( double y : new double[]{-5.5,-1.0,0.0,1.0,5.5} ) { + CodeGen code=new CodeGen("return (arg+0.0)%"+y+";"); + for( long x : new long[]{-17,-1,0,1,17} ) + assertEquals(Double.isNaN(x%y) ? "Double.NaN" : Double.toString(x%y),Eval2.eval(code,x)); + } + assertEquals("-0.0",Eval2.eval(new CodeGen("return -10.0%5.0;"),0)); + assertEquals("1.5",Eval2.eval(new CodeGen("return 7.5%2;"),0)); + } + @Test public void zeroAndDeadBranches() { + assertEquals("0",Eval2.eval(new CodeGen("return 1%arg;"),0)); + assertEquals("0",Eval2.eval(new CodeGen("return 1%0;"),0)); + CodeGen discarded=new CodeGen("1%arg; return 42;").driver(CodeGen.Phase.TypeCheck); + assertNull(discarded._stop.walk(n -> n instanceof ModNode || n instanceof CallNode ? n : null)); + assertEquals("42",Eval2.eval(discarded,0)); + CodeGen common=new CodeGen("return (arg%7)-(arg%7);").driver(CodeGen.Phase.TypeCheck); + assertNull(common._stop.walk(n -> n instanceof ModNode || n instanceof CallNode ? n : null)); + assertEquals("0",Eval2.eval(common,17)); + assertEquals("42",Eval2.eval(new CodeGen("if(arg) return 1%0; return 42;"),0)); + assertEquals("42",Eval2.eval(new CodeGen("if(false) return 1%0; return 42;"),0)); + } + @Test public void operandEffects() { + assertEquals("709",Eval2.eval(new CodeGen(""" + int x=7; + int r=x++%++x; + return r*100+x; + """),0)); + assertEquals("42",Eval2.eval(new CodeGen(""" + val a=new int[1]; + val next={ int[] a -> a[0]++; return a[0]+10; }; + int r=next(a)%next(a); + return r*2+a[0]*10; + """),0)); + } + @Test public void loopsAndRecursiveModes() { + String source=""" + int sum=0; + for(int i=0;i n==0 ? 7.5 : f(n-1)%2; }; + return f(arg); + """),3)); + } + @Test public void typeErrors() { + for( String source : new String[]{"return \"abc\"%2;", "return 2%new int[1];"} ) { + try { + new CodeGen(source).driver(CodeGen.Phase.TypeCheck); + fail("% needs numeric operands: "+source); + } catch(RuntimeException expected) { + assertTrue(expected.getMessage(),expected.getMessage().startsWith("Cannot")); + } + } + } + @Test public void allBackends() { + for( String cpu : new String[]{"x86_64_v2","arm","riscv"} ) + new CheckedCodeGen("return arg%7 + (arg+0.5)%2.5;") + .driver(CodeGen.Phase.Encoding,cpu,"SystemV"); + } + @Test public void nativeRemainders() throws Exception { + TestC.runSYS(""" + val rem_noInline={ i64 x,i64 y -> x%y; }; + val frem_noInline={ f64 x,f64 y -> x%y; }; + val mixed_noInline={ f64 x,f64 y,i64 i -> x*13+(x%y)+y*17+i; }; + val main={ -> + if(rem_noInline(-17,5)!=-2) return 1; + if(rem_noInline(17,-5)!=2) return 2; + if(rem_noInline(sys.integer.MIN_I64,-1)!=0) return 3; + if(rem_noInline(sys.integer.MIN_I64,3)!=-2) return 4; + if(frem_noInline(-7.5,2.0)!=-1.5) return 5; + if(sys.math.f64Bits(frem_noInline(-10.0,5.0))!=sys.integer.MIN_I64) return 6; + sys.libc.set_errno(123); + f64 nan=frem_noInline(1.0,0.0); + if(nan==nan) return 7; + if(sys.libc.errno()!=123) return 8; + if(mixed_noInline(7.5,2.0,31)!=164.0) return 9; + return 0; + }; + ""","modNative","",-1); + } + @Test public void importedRemainders() throws Exception { + Path dir=Files.createTempDirectory(Path.of("build/objs"),"mod-import-"); + new CodeGen(null,dir.toString(),null,"Remainders","val rem_noInline={ i64 x -> x%7; };",126,true,TypeInteger.BOT) + .driver(TestC.CPU_PORT,TestC.CALL_CONVENTION,false,false); + var paths=new Ary<>(new String[]{dir.toString()}); + CodeGen client=new CodeGen(null,dir.toString(),paths,"Client","return Remainders.rem_noInline(arg);",126,true,TypeInteger.BOT); + assertEquals("-3",Eval2.eval(client,-17)); + } + @Test public void nativeDivisionAndRemainderEdges() throws Exception { + TestC.runSYS(integerEdges(),"modDivEdges","",-1); + } + @Test public void emulatedDivisionAndRemainderEdges() throws Exception { + long[] values={Long.MIN_VALUE,Long.MIN_VALUE+1,-17,-1,0,1,17,Long.MAX_VALUE}; + for( String op : new String[]{"%","/"} ) { + String source="val main={ i64 x,i64 y -> x "+op+" y; };"; + EvalArm64 image=TestArm64.build("main",source,0,-1,false); + for( long x : values ) for( long y : values ) { + EvalArm64 arm=new EvalArm64(image._buf,1<<16); + arm._pc=image._pc; + arm.regs[0]=x; arm.regs[1]=y; + assertEquals(0,arm.step(1000)); + assertEquals(x+" "+op+" "+y,y==0 ? 0 : op.equals("%") ? x%y : x/y,arm.regs[0]); + } + // The shared RISC-V emulator's DIV/REM still operate on 32-bit values. + EvalRisc5 rimage=TestRisc5.build(source,"main",0,-1,false); + for( long x : new long[]{-17,-1,0,1,17} ) for( long y : new long[]{-17,-1,0,1,17} ) { + EvalRisc5 riscv=new EvalRisc5(rimage._buf,1<<16); + riscv._pc=rimage._pc; + riscv.regs[10]=x; riscv.regs[11]=y; + assertEquals(0,riscv.step(1000)); + assertEquals(x+" "+op+" "+y,y==0 ? 0 : op.equals("%") ? x%y : x/y,riscv.regs[10]); + } + } + } + private static String integerEdges() { + return integerEdges(new long[]{Long.MIN_VALUE,Long.MIN_VALUE+1,-17,-5,-1,0,1,5,17,Long.MAX_VALUE}); + } + private static String integerEdges(long[] values) { + StringBuilder source=new StringBuilder(""" + val rem_noInline={ i64 x,i64 y -> x%y; }; + val div_noInline={ i64 x,i64 y -> x/y; }; + val main={ -> + """); + int failure=1; + for( long x : values ) + for( long y : values ) { + source.append("if(rem_noInline(").append(literal(x)).append(',').append(literal(y)) + .append(")!=").append(literal(y==0 ? 0 : x%y)).append(") return ").append(failure++).append(';'); + source.append("if(div_noInline(").append(literal(x)).append(',').append(literal(y)) + .append(")!=").append(literal(y==0 ? 0 : x/y)).append(") return ").append(failure++).append(';'); + } + return source.append("return 0; };").toString(); + } + @Test public void nativeFloatingEdges() throws Exception { + double[][] cases={{Double.MAX_VALUE,0.1},{-Double.MAX_VALUE,0.1}, + {Double.MIN_VALUE,1.0},{1.0,Double.POSITIVE_INFINITY}, + {-0.0,Double.NEGATIVE_INFINITY},{-5.0,2.5}, + {Double.POSITIVE_INFINITY,1.0},{Double.NaN,2.0},{2.0,Double.NaN},{1.0,-0.0}}; + StringBuilder source=new StringBuilder("val rem_noInline={ f64 x,f64 y -> x%y; }; val main={ -> "); + for( int i=0; i + i64 x=a[0]; + i64 y=flag ? a[1] : a[2]; + return x==y; + }; + val add_noInline={ i64[] a, int flag -> + i64 x=a[0]; + i64 y=flag ? a[1] : a[2]; + return x+y; + }; + val main={ -> + val a=new i64[3]; a[0]=17; a[1]=17; a[2]=23; + if(!compare_noInline(a,1) || compare_noInline(a,0)) return 1; + if(add_noInline(a,1)!=34 || add_noInline(a,0)!=40) return 2; + return 0; + }; + ""","scheduleLaterOperands","",-1); + } + + @Test public void nativeLoadsAcrossWrites() throws Exception { + TestC.runSYS(""" + val change_noInline={ i64[] a -> a[0]=a[1]; return a[0]; }; + val compare_noInline={ i64[] a -> + i64 x=a[0]; + return x==change_noInline(a); + }; + val add_noInline={ i64[] a -> + i64 x=a[0]; + return x+change_noInline(a); + }; + val main={ -> + val a=new i64[2]; a[0]=17; a[1]=23; + if(compare_noInline(a)) return 1; + a[0]=17; a[1]=29; + if(add_noInline(a)!=46) return 2; + return 0; + }; + ""","scheduleAcrossWrites","",-1); + } +} diff --git a/chapter31/src/test/java/com/seaofnodes/simple/StreamIOTest.java b/chapter31/src/test/java/com/seaofnodes/simple/StreamIOTest.java index 7b459e75..79b95c03 100644 --- a/chapter31/src/test/java/com/seaofnodes/simple/StreamIOTest.java +++ b/chapter31/src/test/java/com/seaofnodes/simple/StreamIOTest.java @@ -88,7 +88,7 @@ public class StreamIOTest extends TestC { val bytes=sys.io.read(700); if(!bytes) return 1; if(bytes#!=24593) return 2; - for(u32 i=0; i bool }`. +- Bare forward types use file-qualified names. Missing required types produce + source diagnostics. Store-width discovery waits for the forward pointer type + upgrade so worklist notification is preserved. +- A final constant method target comes from its declaration. Loading it must not + discard its identity merely because it has not escaped to outside code. +- Do not use ordinary HashMap/HashSet with Node keys for bookkeeping: + Node.hashCode participates in GVN locking. Use identity maps/sets. +- Breakout keeps input history in Game; there is no separate Controls class now. + Debounce's callback returns int because audio.stop returns i32; the result is + ignored. Boosted brick hits use sound 3 and the brick's soundDepth, not sound 4. + The old collisionsAndBoost sound expectations are fixed. + +Keep arithmetic compact, but space assignments, compound assignments, and +relational operators. Preserve deliberate column alignment above other spacing +rules. Time values use `_ms`/`_msec` suffixes; timer IDs have a smaller unsigned +type. Prefer named bounds and products of time units to large magic numbers. + +Build and test from the chapter directory using the existing Java harness; +do not add Python code or test drivers. Useful commands are `make breakout +CTAGS=`, `make test CLASS=BreakoutTest CTAGS=`, and `make test CLASS=GraphicsTest +METHOD=breakoutInputAndFrames CTAGS=`. Native coverage matters: Eval2 cannot +detect instruction encoding or relocation errors. Use identity for relocation +sites because equal constant loads can still require separate relocations. +X86 floating comparisons use UCOMISD's CF/ZF/PF, preserve unordered behavior +when negating a branch, and must not use signed SF/OF conditions. + +At this reset, the 752-test suite excluding BreakoutTest and GraphicsTest passed, +the Breakout input/render smoke test passed, and all five BreakoutTest tests +passed. These are dated results, not a fixed expected count. Earlier logs with +receiver, forward-type, callback-target, or collision failures are superseded. +No test process is left running. Do not rerun unchanged checks just for a reset. + +Default builds/tests are offline and need no display or audio hardware. Only +explicit `make libs`/`init` (legacy `lib`) may download dependencies. Cache them +under `lib/`, never `build/`; clean must preserve the cache. Missing dependencies +fail promptly. Interactive launch targets are explicit; `SIMPLE_MINIFB=off` and +`SIMPLE_MINIAUDIO=off` select headless tests. Build released sys objects before +running native clients, including single-test targets. Runnable examples belong +in `docs/examples`. Keep new and edited text LF-only. +Shared `build-support/java.mk` and `libraries.mk` own the common build and +download rules. Keep chapter Makefile differences limited to introduced +features; cached JARs may be copied between chapters during offline builds. +Keep inherited Java test names. MiniFB discovery supports executable-relative +and chapter build paths; examples should run without environment setup. + +Clock button input is caller-fed and fires on release inside after a press +inside. Its drawing widget has no native-window dependency. Time/animation +already belong in this chapter. Time parsing uses -1 for absolute parse errors +by Cliff's choice; relative time parsing remains deferred. UTC is the default +for time interpolation; local-zone formatting is an explicit library call. +Hex literals use 0x/0X and octal uses a leading zero, not 0o. ## Chapter 30 starting point (2026-11-07; superseded by Chapter 31) -Cliff committed the Chapter 29 work as `bb9b30b2c` and requested merging -`escape-flow` into `main`, then starting Chapter 30. Local `main` now includes -that commit. The working branch is `ch30`, with a complete `chapter30/` copy -and build/IDE entries. Small games drive compiler and sys-library improvements, -starting with ASCII tic-tac-toe; the games are workloads, not the chapter's theme. -Runnable examples belong in `chapter30/docs/examples`, not `src/test/smp/examples`. -Do not add Python to the codebase or use Python test drivers; use the existing -Java test harness. -Chapter 29 retains the completed compiler and documentation. Inherited Java -test names keep their historical identities. +Chapter 30 is the preceding snapshot. Its old branch and startup instructions +are superseded by the Chapter 31 guidance above. `ScopeNode.dup()` shares `Kind` boundaries and `Var` records. When pruning a saved break/continue scope, use `_pop()` and copy surviving forward references @@ -109,21 +124,10 @@ with `balanceLoopFRefs`; `pop()` promotes them by mutating shared boundaries and indices while the active scope still has its old binding order. Merge jump scopes with loop-reference balancing, not `balanceIf`'s declaration checks. -## Historical restart handoff (2026-11-06; superseded by Chapter 30) +## Escape-flow implementation lessons -Cliff requested this handoff before restarting. Active branch is `escape-flow`, -tracking `origin/escape-flow`; HEAD is `8f460340c`. `ch29-cleanup` was previously -fast-forwarded into local `main`, then this branch was created. The escape-flow -implementation is still **uncommitted and unstaged**. Preserve all working-tree -changes, including untracked `chapter29/docs/escape-flow.md` and -`chapter29/src/test/java/com/seaofnodes/simple/EscapeFlowTest.java`. No commit, -push, or chapter split is currently requested. Cliff thinks this may deserve -its own chapter; keep working in Chapter29 until that decision is made. - -Read [the escape-flow design](../chapter29/docs/escape-flow.md) first. It is the -current account; the later sections of deferred-construction.md retain older -failed experiments and are explicitly superseded. The implementation is a -tested first pass, not a claim that all outside-value precision is solved. +See [the escape-flow design](../chapter29/docs/escape-flow.md). These are reusable +implementation facts; old branch status and validation logs remain in Git. Important implementation choices for review/resumption: @@ -162,50 +166,10 @@ in EscapeFlowTest.testUnknownCallerCallback now proves that only `` and object/callback merge can also have an abstract pointer type, so do not cap arbitrary TypePtr values at outside escapes. -Validation saved under ignored `build/`: - -- `xint-alloc-build.log` and `xint-alloc-chapter*.log`: all five XInt chapters - (26/27/28a/28b/29) rebuild; 134 focused type, escape, module, and import tests - pass after renaming the pooled allocator to `XInt.alloc` and using it for - the three foreign-set builders. It returns zeroed mutable storage to fill - and pass to `intern`; `_free` still returns storage to the pool. -- `escape-string-reorder-final.log`: full 28a/28b/29 suites pass after the - String declaration reorder and measured spill expectations (538/578/601 - active tests), plus shared printer and ISA checks. -- `escape-backport-final.log`: combined full Make run for 28a/28b/29, - respectively 538/578/601 active tests pass with assertions, plus shared - printer and ISA checks. Added allocator, unknown-callback cycle, and saved - private-function exclusion coverage. Destination baselines are recorded in - `escape-backport-baseline.log` (531 in 28a, 571 in 28b). -- `remove-public-interface-tests.log`: full Chapter29 `make -k tests CTAGS=`, - all 598 active tests pass after removing the frozen public-interface inventory - and moving its test coverage to the converged escape sets. -- `class-self-default-tests.log`: full Chapter29 `make -k tests CTAGS=`, all - 598 active tests pass after sharpening the hidden receiver default, including - the retained escape-exclusion assertion. No printed-IR golden changed. -- `escape-flow-complete.log`: full Chapter29 `make -k tests`, all 598 active - tests pass with assertions (404 raw0, 38 raw1, 13 standalone, 29 system, - 1 fuzzer, 113 aggregate). -- `escape-flow-last-check.log`: 26 tests pass after the final small CLInit guard - cleanup: ClassInitDependenciesTest, ConvertNodeTest, EscapeFlowTest. -- `EscapeSeeds.java` / `.class`: four recursive programs across four worklist - seeds, 16 checks pass against unchanged expected IR. Sources are in - `build/remaining-failures/*.smp`. The four are Chapter12 testCoRecur, - testCoRecur2, testCoRecur3, and testPrivateRecursiveReturn. -- `EscapeLoads.java` and `OutsideCallback.java` are disposable diagnostic - harnesses; `escape-flow-*.log` includes intermediate failures. Use the final - logs above, not an earlier trial, as the validation baseline. - -Run Make from `chapter29`; use the existing JUnit classpath -`build/classes/main;build/classes/test;lib/*`. No tests/JVMs are left running. -Do not recreate tmp/* experiment directories. No new whole-IR passes, side IR, -IterPeeps escape-repair hooks, or relaxed goldens were introduced. There is no -need to rerun unchanged checks merely because the conversation restarted. - -## Current workspace (2026-11-06) +## Chapter 29 parser snapshot (historical) Chapter 29 is **Tech Debt Cleanup**. Cliff approved keeping the parser split -and moving it into this new snapshot; continue parser work there. Chapter 28b +and moving it into that snapshot; current work belongs in Chapter 31. Chapter 28b retains the original parser. The new `parser/` package follows the grammar; `Var` belongs there and `IterPeeps` belongs in `codegen/`. -- cgit v1.2.3