diff options
Diffstat (limited to 'chapter31/README.md')
| -rw-r--r-- | chapter31/README.md | 150 |
1 files changed, 129 insertions, 21 deletions
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 ``` |
