summaryrefslogtreecommitdiff
path: root/chapter29
diff options
context:
space:
mode:
authorCliff Click <cliffc@acm.org>2026-11-15 11:20:40 -0800
committerCliff Click <cliffc@acm.org>2026-11-15 11:20:40 -0800
commitf0a6c6757a795b8e186de0076836a87acef59fa7 (patch)
treeef45c1b58093420bbd2de6647274139e46539bfe /chapter29
parent7e66b7ae6b00a2e1652db32f01f0bf480508ef05 (diff)
downloadSimple-f0a6c6757a795b8e186de0076836a87acef59fa7.tar.gz
Simple-f0a6c6757a795b8e186de0076836a87acef59fa7.zip
Graphics now allow resizemain
Reorganize docs. Fix bugs X86 LOad+cmp scheduling. Math intrinsics
Diffstat (limited to 'chapter29')
-rw-r--r--chapter29/README.md51
-rw-r--r--chapter29/docs/construction-groups.md6
-rw-r--r--chapter29/docs/deferred-construction.md5
-rw-r--r--chapter29/docs/escape-flow.md6
4 files changed, 65 insertions, 3 deletions
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`.