Skip to content

Add Runtime Basics chapter#566

Merged
SeanTAllen merged 3 commits intomainfrom
sean/runtime-basics
Mar 4, 2026
Merged

Add Runtime Basics chapter#566
SeanTAllen merged 3 commits intomainfrom
sean/runtime-basics

Conversation

@SeanTAllen
Copy link
Member

Adds a new chapter covering Pony runtime internals, placed between C-FFI and Gotchas in the nav. The chapter has six pages:

  • The Scheduler: cooperative scheduling, scheduler threads, work stealing, batch processing
  • Program Lifecycle: startup, actor states (alive/dead, running/waiting/blocked/muted), quiescence and shutdown, exit codes
  • Garbage Collection: intra-actor GC (per-actor heaps, no stop-the-world), inter-actor GC via ORCA (cycle detector)
  • The ASIO Subsystem: dedicated I/O thread, platform backends, effect on actor lifetime
  • Backpressure: automatic muting of senders to overloaded actors
  • Runtime Options: all --pony* command-line flags plus @runtime_override_defaults

The two appendix pages (Memory Allocation at Runtime and Garbage Collection with Pony-ORCA) are superseded by the new GC page and removed, with 301 redirects added in netlify.toml. Cross-references are added from the scheduling and GC gotcha pages, and the compiler-args appendix now points to the new Runtime Options page.

Adapted in part from rhagenson's earlier work on the runtime-basics branch.

Closes #408

The tutorial previously scattered runtime information across gotchas and
appendices without a cohesive chapter. This adds a dedicated chapter
covering the scheduler, program lifecycle, garbage collection (both
intra-actor and ORCA), ASIO, backpressure, and runtime options.

The two superseded appendix pages (Memory Allocation at Runtime and
Garbage Collection with Pony-ORCA) are removed, with their content
folded into the new GC page and redirects added in netlify.toml.
Cross-references are added from the scheduling and GC gotcha pages, and
the compiler-args appendix now points to the new Runtime Options page.

Adapted in part from rhagenson's earlier work on the runtime-basics
branch.

Closes #408
@netlify
Copy link

netlify bot commented Feb 28, 2026

Deploy Preview for pony-tutorial ready!

Name Link
🔨 Latest commit 571a317
🔍 Latest deploy log https://app.netlify.com/projects/pony-tutorial/deploys/69a25a6e55fe650008c9ed58
😎 Deploy Preview https://deploy-preview-566--pony-tutorial.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@ponylang-main ponylang-main added the discuss during sync Should be discussed during an upcoming sync label Feb 28, 2026
@SeanTAllen SeanTAllen merged commit 5236d0a into main Mar 4, 2026
10 checks passed
@SeanTAllen SeanTAllen deleted the sean/runtime-basics branch March 4, 2026 21:06
@ponylang-main ponylang-main removed the discuss during sync Should be discussed during an upcoming sync label Mar 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add "Runtime basics" to the tutorial

3 participants