{"id":49695789,"url":"https://github.com/aether-lang-org/aether","last_synced_at":"2026-05-13T21:01:52.924Z","repository":{"id":340061594,"uuid":"944236568","full_name":"aether-lang-org/aether","owner":"aether-lang-org","description":"A compiled actor-based programming language with type inference, designed for concurrent systems. ","archived":false,"fork":false,"pushed_at":"2026-05-10T13:30:53.000Z","size":30169,"stargazers_count":91,"open_issues_count":14,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-05-10T14:52:36.521Z","etag":null,"topics":["actor-model","c","compiler","concurrency","embedded-c","message-passing","open-source","pattern-matching","programming-language","systems-programming","type-inference","wasm"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aether-lang-org.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["nicolasmd87"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2025-03-07T02:23:27.000Z","updated_at":"2026-05-10T13:30:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aether-lang-org/aether","commit_stats":null,"previous_names":["nicolasmd87/aether","aether-lang-org/aether"],"tags_count":137,"template":false,"template_full_name":null,"purl":"pkg:github/aether-lang-org/aether","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aether-lang-org%2Faether","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aether-lang-org%2Faether/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aether-lang-org%2Faether/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aether-lang-org%2Faether/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aether-lang-org","download_url":"https://codeload.github.com/aether-lang-org/aether/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aether-lang-org%2Faether/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32999522,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"ssl_error","status_checked_at":"2026-05-13T13:14:51.610Z","response_time":115,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["actor-model","c","compiler","concurrency","embedded-c","message-passing","open-source","pattern-matching","programming-language","systems-programming","type-inference","wasm"],"created_at":"2026-05-08T00:04:18.954Z","updated_at":"2026-05-13T21:01:52.912Z","avatar_url":"https://github.com/aether-lang-org.png","language":"C","funding_links":["https://github.com/sponsors/nicolasmd87"],"categories":[],"sub_categories":[],"readme":"# Aether Programming Language\n\n[![CI](https://github.com/nicolasmd87/aether/actions/workflows/ci.yml/badge.svg)](https://github.com/nicolasmd87/aether/actions/workflows/ci.yml)\n[![Windows](https://github.com/nicolasmd87/aether/actions/workflows/windows.yml/badge.svg)](https://github.com/nicolasmd87/aether/actions/workflows/windows.yml)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS%20%7C%20WASM%20%7C%20Embedded-lightgrey)]()\n\nA compiled actor-based programming language with type inference, designed for concurrent systems. Aether compiles to C for native performance and seamless C interoperability.\n\n## Overview\n\nAether is a compiled language that brings actor-based concurrency to systems programming. The compiler generates readable C code, providing portability and interoperability with existing C libraries.\n\n**Core Features:**\n- Actor-based concurrency with automatic multi-core scheduling\n- Type inference with optional annotations\n- Compiles to readable C for portability and C library interop\n- Lock-free message passing with adaptive optimizations\n- Three-layer capability model for sandboxing untrusted code and hosting other languages in-process — `--emit=lib` gates stdlib at compile time, `hide`/`seal except` gates scopes, LD_PRELOAD gates libc\n- Go-style result types: `a, err = func()` with `_` discard\n- Package management: `ae add host/user/repo[@version]` (GitHub, GitLab, Bitbucket, any git host)\n- Production-grade HTTP server in stdlib — TLS, HTTP/1.1 keep-alive, **HTTP/2** (h2 + h2c via libnghttp2 with ALPN, GOAWAY graceful shutdown, server-level pthread pool for concurrent stream dispatch), WebSocket (RFC 6455), Server-Sent Events, **zero-copy `sendfile(2)` static-file serving** (Linux + macOS, with TCP_CORK / TCP_NOPUSH coalescing), plus a stack of composable middleware (CORS, basic/bearer/session-cookie auth, rate limiting, real-IP, vhost, gzip, static files, rewrite, error pages), `/healthz` + `/readyz` health probes, structured access logs, and Prometheus metrics. See [HTTP Server](docs/http-server.md).\n- nginx-class **reverse proxy** in stdlib — `std.http.proxy` forwards inbound requests to a pool of upstream servers with five load-balancing algorithms (round-robin / least-conn / ip-hash / smooth weighted RR / cookie-hash sticky), active health checks, in-memory LRU response cache with Vary-aware keying and RFC 7234 cacheability rules, per-upstream circuit breaker, idempotent retry with `proxy_next_upstream` semantics, per-upstream token-bucket rate limit, active drain, W3C Trace-Context propagation, and a Prometheus 0.0.4 metrics endpoint. Hop-by-Hop header handling per RFC 7230. See [Reverse Proxy](docs/http-reverse-proxy.md).\n- **`--emit=lib` symbol catalog (`aether_lib_meta`) + `ae lib-info` reflection** — every shared library Aether emits exports a single zero-allocation, layout-stable `static const AetherLibMeta*` describing every exported function (Aether name, C symbol, signature, source file, source line). Walks straight from Python ctypes / Java Panama / Ruby Fiddle / Go cgo / hand-rolled `dlsym` — no JSON, no parsing, the catalog literally lives in `.rodata`. Schema is versioned (`\"1.0\"`) with explicit append-only growth at the struct tail (closure-context records reserved for v2). `ae lib-info \u003cpath\u003e` is a turnkey reader: dlopen → format-print the catalog. See [Reflection: the symbol catalog](docs/emit-lib.md#reflection-the-symbol-catalog-aether_lib_meta--403).\n- **`--emit=lib` resource caps** — sandbox untrusted Aether plugins inside trusted hosts. Embedders set a process-wide memory ceiling (`aether_set_memory_cap`) and per-thread wall-clock deadline (`aether_set_call_deadline`) via the public C surface in `include/libaether.h`. The codegen emits a tripwire at every loop head under `--emit=lib` (zero overhead on `--emit=exe`), so guests that allocate uncapped or spin in infinite loops are bounded predictably. Memory accounting tracks current usage, not high-water-mark, so long-running guests aren't tripped by cumulative churn.\n- **DSL block receiver scoping** — inside `receiver.method(args) { body }`, bare-name function references resolve through the receiver's namespace before erroring. SDK builders no longer require an `import X (setter1, setter2, ...)` line to make trailing-block setters resolve.\n- **`@derive(eq)` on structs** — annotate a struct with `@derive(eq)` to synthesize `int T_eq(T a, T b)` automatically (field-by-field `==` chain); supports primitive numeric and string fields.\n- **Automatic string-ownership tracking** — every string variable carries a compiler-emitted `_heap_\u003cname\u003e` companion that flips on every reassignment, so heap-allocated buffers are reclaimed eagerly without an explicit `defer string.free(s)`. Covers single-value reassignment, tuple destructure, cross-block flow, function-exit cleanup, and escape detection through call-args (`@retain` annotation marks \"stored\" parameters; default `string`-param treatment is read-only). Recognised heap sources include stdlib `string.concat` / `substring` / `to_upper` / `to_lower` / `trim`, string interpolation, user-defined `-\u003e string` functions whose body provably returns heap (recursive structural escape analysis with cycle detection), and tuple-returning externs annotated `(string @heap, ...)`. See [String memory model](docs/memory-management.md#string-memory-model-heap-string-tracker) for the full picture.\n- **Eiffel-style runtime contracts** — `requires` and `ensures` clauses attach pre/postconditions directly to function declarations: `add(a, b) -\u003e int requires a \u003e= 0 ensures result \u003e= a { return a + b }`. Each clause lowers to `if (!(\u003cexpr\u003e)) aether_panic(\"\u003crole\u003e violation: \u003ctext\u003e in \u003cfn\u003e\");` — preconditions at function entry, postconditions before every `return` (with `result` bound to the about-to-be-returned value). Multiple clauses, freely interleaved, each checked independently so the panic message names the specific failed predicate. `--no-contracts` build flag suppresses emission entirely (zero per-call cost — the analog of C's `-DNDEBUG`). See [Function contracts](docs/language-reference.md#function-contracts-requires--ensures-issue-348).\n\n## Runtime Features\n\nThe Aether runtime implements a native actor system with optimized message passing:\n\n### Concurrency Model\n- **Multi-core partitioned scheduler** with locality-aware actor placement\n- **Locality-aware spawning** — actors placed on the caller's core for efficient parent-child messaging\n- **Message-driven migration** — communicating actors automatically converge onto the same core\n- **Work-stealing fallback** for idle core balancing\n- **Lock-free SPSC queues** for same-core messaging\n- **Cross-core messaging** with lock-free mailboxes\n\n### Memory Management\n- **Manual by default** — use `defer` for cleanup. All allocations cleaned up explicitly.\n- **Automatic string-ownership tracking** — heap-allocated strings auto-freed on reassignment, tuple destructure, and function exit; opt-in `@retain` extern annotation for parameters that store the pointer beyond the call. See [String memory model](docs/memory-management.md#string-memory-model-heap-string-tracker).\n- **Arena allocators** for actor lifetimes\n- **Memory pools** with thread-local allocation\n- **Actor pooling** reducing allocation overhead\n- **Zero-copy message delivery** in single-actor main-thread mode (caller stack passed directly)\n\n### Message Optimization\n- **Sender-side batching** for reduced overhead\n- **Message coalescing** for higher throughput\n- **Adaptive batching** dynamically adjusts batch sizes\n- **Direct send** for same-core actors bypasses queues\n\n### Capabilities \u0026 Sandboxing\n\nAether is compiled, but comes with a capability system normally associated with interpreted / VM-hosted languages. Three enforcement layers:\n\n- **Compile-time module gate** — `--emit=lib` rejects `std.fs` / `std.net` / `std.os` imports by default; the host opts each in with `--with=fs,net,os`.\n- **Compile-time scope gate** — `hide \u003cnames\u003e` and `seal except \u003callowlist\u003e` on any lexical block (closure, trailing-block DSL, actor handler) block ambient names from leaking into contained code.\n- **Runtime process gate** — `libaether_sandbox.so` (LD_PRELOAD) intercepts libc (`open*`, `connect`/`bind`, `execve`, `mmap`, `dlopen`, `getenv`) against a builder-DSL grant list; inherited across `execve` to child processes.\n\nThe same grant list + LD_PRELOAD also contains embedded interpreters — an Aether `main()` can host Lua, Python, Perl, Ruby, Tcl, and JavaScript in-process (`contrib.host.\u003clang\u003e.run_sandboxed(perms, code)`) with the same permission model that scopes Aether's own libc calls. In the reverse direction, `--emit=lib` + `ae build --namespace` produce a `.so` plus a typed SDK (Python ctypes, Java Panama, Ruby Fiddle) so host-language apps can embed Aether without writing FFI by hand.\n\nMashup of Pony object capabilities, Java's removed SecurityManager, and a fraction of gVisor — see [Containment Sandbox](docs/containment-sandbox.md) for the full comparison, threat model, and known bypass surface.\n\n### Platform Portability\n- **Compile-time platform detection** via `AETHER_HAS_*` flags (threads, atomics, filesystem, networking, NUMA, SIMD, affinity)\n- **Cooperative scheduler** for single-threaded platforms (WebAssembly, embedded, bare-metal)\n- **Graceful degradation** — stdlib stubs return errors when features are unavailable\n- **`ae build --target wasm`** compiles to WebAssembly via Emscripten\n- **`PLATFORM=wasm|embedded`** Makefile targets for cross-compilation\n- **Docker CI images** for Emscripten (WASM) and ARM (embedded) verification\n\n### Advanced Features\n- **Actor timeouts** — `receive { ... } after N -\u003e { ... }` fires handler if no message arrives within N ms\n- **Cooperative preemption** (opt-in) — `AETHER_PREEMPT=1` breaks long handlers, `--preempt` yields at loop back-edges\n- **Reactor-pattern async I/O** — `net.await_io(fd)` suspends an actor on a file descriptor without blocking any scheduler thread; the runtime's per-core I/O poller (epoll/kqueue/poll) delivers an `IoReady { fd, events }` message when the fd becomes readable\n- **SIMD batch processing** with AVX2 support\n- **NUMA-aware allocation** for multi-socket systems\n- **CPU feature detection** for runtime optimization selection\n- **Performance profiling** with per-core cycle counting\n- **Message tracing** for debugging\n\n### Benchmarks\n\nCross-language benchmark suite based on the [Savina Actor Benchmark Suite](https://dl.acm.org/doi/10.1145/2687357.2687368) — 11 languages × 5 patterns (ping-pong, counting, thread ring, fork-join, skynet). Both the benchmark runner and the visualization server are written in Aether, dogfooding the stdlib.\n\n```bash\nmake benchmark    # Builds runner, runs all 55 benchmarks, opens UI at http://localhost:8080\n```\n\nSee [Performance Benchmarks](docs/performance-benchmarks.md) for methodology and [benchmarks/cross-language/](benchmarks/cross-language/) for source.\n\n## Quick Start\n\n### Install\n\n**Linux / macOS — one-line install:**\n\n```bash\ngit clone https://github.com/nicolasmd87/aether.git\ncd aether\n./install.sh\n```\n\nInstalls to `~/.aether` and adds `ae` to your PATH. Restart your terminal or run `source ~/.bashrc`, `~/.zshrc`, or `~/.bash_profile`.\n\n**Windows — download and run:**\n\n1. Download `aether-*-windows-x86_64.zip` from [Releases](https://github.com/nicolasmd87/aether/releases)\n2. Extract to any folder (e.g. `C:\\aether`)\n3. Add `C:\\aether\\bin` to your PATH\n4. **Restart your terminal** (so PATH takes effect)\n5. Run `ae init hello \u0026\u0026 cd hello \u0026\u0026 ae run`\n\nGCC is downloaded automatically the first time you run a program (~80 MB, one-time) — no MSYS2 or manual toolchain setup required.\n\n**All platforms — manage versions with `ae version`:**\n\n```bash\nae version list              # see all available releases\nae version install v0.25.0   # download and install a specific version\nae version use v0.25.0       # switch to that version\n```\n\n### Your First Program\n\n```bash\n# Create a new project\nae init hello\ncd hello\nae run\n```\n\nOr run a single file directly:\n\n```bash\nae run examples/basics/hello.ae\n```\n\n### Editor Setup (Optional)\n\nInstall syntax highlighting for a better coding experience:\n\n**VS Code / Cursor:**\n```bash\ncd editor/vscode\n./install.sh\n```\n\nThis provides:\n- Syntax highlighting with TextMate grammar\n- Custom \"Aether Erlang\" dark theme\n- `.ae` file icons\n\n### Development Build (without installing)\n\nIf you prefer to build without installing:\n\n```bash\nmake ae\n./build/ae version\n./build/ae run examples/basics/hello.ae\n```\n\n### The `ae` Command\n\n`ae` is the single entry point for everything — like `go` or `cargo`:\n\n```bash\nae init \u003cname\u003e           # Create a new project\nae run [file.ae]         # Compile and run (file or project)\nae build [file.ae]       # Compile to executable\nae check [file.ae]       # Type-check without compiling (skips codegen + link)\nae test [file|dir]       # Discover and run tests\nae examples [dir]        # Build all example programs\nae add \u003chost/user/repo\u003e  # Add a dependency (any git host)\nae repl                  # Start interactive REPL\nae cache                 # Show build cache info\nae cache clear           # Clear the build cache\nae version               # Show current version\nae version list          # List all available releases\nae version install \u003cv\u003e   # Install a specific version\nae version use \u003cv\u003e       # Switch to an installed version\nae help                  # Show all commands\n```\n\nIn a project directory (with `aether.toml`), `ae run` and `ae build` compile `src/main.ae` as the program entry point. You can also pass `.` as the directory: `ae run .` or `ae build .`.\n\n**Using Make (alternative):**\n\n```bash\nmake compiler                    # Build compiler only\nmake ae                          # Build ae CLI tool\nmake test                        # Run runtime C test suite (166 tests)\nmake test-ae                     # Run .ae source tests (95 tests)\nmake test-all                    # Run all tests\nmake examples                    # Build all examples\nmake -j8                         # Parallel build\nmake help                        # Show all targets\n```\n\n### Building on Windows\n\nThe Aether build is GNU-make based. Use one of the two paths below — `nmake` from a Visual Studio Developer Prompt **will not work** (the Makefile uses GNU-only syntax that NMAKE can't parse).\n\n**Just running Aether? Skip this section** and use the [release binary](https://github.com/nicolasmd87/aether/releases) — no MSYS2 setup required.\n\n**Building from source — recommended (MSYS2 / MinGW-w64):**\n\n1. Install [MSYS2](https://www.msys2.org/) and open the **MSYS2 MinGW 64-bit** shell (not the bare MSYS shell).\n2. Install the toolchain:\n   ```bash\n   pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-make \\\n             mingw-w64-x86_64-openssl mingw-w64-x86_64-zlib \\\n             mingw-w64-x86_64-ca-certificates pkg-config make bc\n   ```\n3. Clone and build:\n   ```bash\n   git clone https://github.com/nicolasmd87/aether.git\n   cd aether\n   make ci   # full suite: compiler, ae, stdlib, REPL, C tests, .ae tests, examples\n   ```\n\nFor HTTPS to verify certs, the `mingw-w64-x86_64-ca-certificates` package above provides the bundle at `/mingw64/etc/ssl/certs/ca-bundle.crt`. The runtime auto-detects it; if your install is in a non-standard location, export `SSL_CERT_FILE` to the bundle's Windows path.\n\n**Native MSVC (cl.exe / nmake):** not currently supported as a full build path — tracker [#99](https://github.com/nicolasmd87/aether/issues/99). The MSVC matrix job in CI verifies our public headers parse under `cl.exe` so a future native MSVC port stays feasible, but `make` (the build system itself) requires GNU make. The MSYS2 MinGW build above is the supported source-build path for Windows today.\n\n## Project Structure\n\n```\naether/\n├── compiler/           # Aether compiler (lexer, parser, codegen)\n│   ├── parser/        # Lexer, parser, tokens\n│   ├── analysis/      # Type checker, type inference\n│   ├── codegen/       # C code generation, optimizer\n│   └── aetherc.c      # Compiler entry point\n├── runtime/           # Runtime system\n│   ├── actors/        # Actor implementation and lock-free mailboxes\n│   ├── config/        # Platform detection, optimization tiers, runtime config\n│   ├── memory/        # Arena allocators, memory pools, batch allocation\n│   ├── scheduler/     # Multi-core scheduler + cooperative single-threaded backend\n│   └── utils/         # CPU detection, SIMD, tracing, thread portability\n├── std/                # Standard library\n│   ├── string/         # String operations\n│   ├── file/           # File operations (open, read, write, delete)\n│   ├── dir/            # Directory operations (create, delete, list)\n│   ├── path/           # Path utilities (join, basename, dirname)\n│   ├── fs/             # Combined file/dir/path module\n│   ├── collections/    # List, HashMap, Vector, Set, PQueue\n│   ├── list/           # Dynamic array (ArrayList)\n│   ├── map/            # Hash map\n│   ├── intarr/         # Fixed-size packed int buffer\n│   ├── json/           # JSON parser and builder\n│   ├── http/           # HTTP client + server (TLS, keep-alive, h2, WS, SSE, metrics)\n│   │   ├── client/         # Builder client (request builder, full response, JSON sugar)\n│   │   ├── middleware/     # CORS, basic/bearer/session auth, rate-limit, real-IP, vhost, gzip, static, rewrite, error pages\n│   │   ├── proxy/          # Reverse proxy: upstream pool, LB (RR/LC/iphash/WRR), health, cache, circuit breaker\n│   │   ├── server/h2/      # HTTP/2 framing via libnghttp2 (h2 + h2c + ALPN + GOAWAY + concurrent dispatch)\n│   │   └── server/vcr/     # Servirtium-format record/replay for HTTP tests\n│   ├── tcp/            # TCP client and server\n│   ├── net/            # Combined TCP/HTTP networking module\n│   ├── cryptography/   # SHA-1, SHA-256\n│   ├── zlib/           # One-shot deflate/inflate\n│   ├── math/           # Math functions and random numbers\n│   ├── io/             # Console I/O, environment variables\n│   ├── os/             # Shell execution, command capture, env vars, ISO-8601 time\n│   └── log/            # Structured logging\n├── contrib/            # Optional / opinionated modules outside std/\n│   ├── sqlite/         # SQLite bindings (open, prepare, bind, step, column, ...)\n│   ├── tinyweb/        # Server-side request/response DSL\n│   ├── host/\u003clang\u003e/    # Embed Lua, Python, Perl, Ruby, Tcl, JS in-process\n│   └── climate_http_tests/ # Servirtium climate-API record/replay fixtures\n├── tools/              # Developer tools\n│   ├── ae.c            # Unified CLI tool (ae command)\n│   └── apkg/           # Project tooling, TOML parser\n├── tests/              # Test suite (runtime, syntax, integration, regression)\n├── examples/           # Example programs (.ae files)\n│   ├── basics/         # Hello world, variables, arrays, etc.\n│   ├── actors/         # Actor patterns (ping-pong, pipeline, etc.)\n│   └── applications/   # Complete applications\n├── docs/               # Documentation\n└── docker/             # Docker (CI, dev, WASM, embedded)\n```\n\n## Language Example\n\n```aether\n// Counter actor with message handling\nmessage Increment {}\nmessage Decrement {}\nmessage Reset {}\n\nactor Counter {\n    state count = 0\n\n    receive {\n        Increment() -\u003e {\n            count = count + 1\n        }\n        Decrement() -\u003e {\n            count = count - 1\n        }\n        Reset() -\u003e {\n            count = 0\n        }\n    }\n}\n\nmain() {\n    // Spawn counter actor\n    counter = spawn(Counter())\n\n    // Send messages\n    counter ! Increment {}\n    counter ! Increment {}\n    counter ! Decrement {}\n    counter ! Reset {}\n    counter ! Increment {}\n\n    // Wait for all messages to be processed\n    wait_for_idle()\n\n    println(\"Final count: ${counter.count}\")\n}\n```\n\n## Closures and Builder DSL\n\nAether closures take three shapes after a function call. They look similar but have different semantics — picking the right one is the language's main lever for separating DSL structure from runtime behaviour.\n\n| Mode | Syntax | Semantics |\n|------|--------|-----------|\n| **Immediate** | `func() { block }` | Runs inline at the call site — used for DSL structure |\n| **Closure** | `func() \\|x\\| { block }` | Real closure with explicit params, hoisted to a C function |\n| **Callback** | `func() callback { block }` | Real closure that captures enclosing scope — no params needed |\n\n```aether\n// Immediate — declarative structure, runs during construction\npanel(\"Settings\") {\n    button(\"OK\")\n    button(\"Cancel\")\n}\n\n// Closure — explicit params, deferred invocation\napply_twice(x: int, f: fn) { return call(f, call(f, x)) }\ndoubler = |x: int| -\u003e x * 2\nprintln(apply_twice(3, doubler))    // 12\n\n// Callback — captures from scope, runs when invoked\ncounter = ref(0)\nbtn(\"increment\") callback { ref_set(counter, ref_get(counter) + 1) }\nbtn(\"decrement\") callback { ref_set(counter, ref_get(counter) - 1) }\n```\n\nThe compiler distinguishes them at parse time, which is what makes the sandboxing story (above) work: `hide`/`seal except` checks happen against the hoisted form of `closure` and `callback` blocks, so a `seal except req, res` on a callback body genuinely prevents the body from reaching outer scope. Immediate blocks inherit the caller's lexical scope by design — they're structure, not callbacks.\n\nInspired by Smalltalk blocks, Ruby's blocks/procs, Groovy closures, and Kotlin/SwiftUI's trailing-block DSLs. See [Closures and Builder DSL](docs/closures-and-builder-dsl.md) for the builder-context mechanism, ref cells, and full DSL pattern.\n\n## Config IS Code\n\n**Don't ship a YAML loader.** If your Aether library has a \"start the thing\" surface — HTTP server, daemon, agent, scheduler, test rig — expose it as a closure-DSL block and let the operator's \"config\" be a `.ae` file they run with `ae run`. The pattern collapses YAML → templating → second-language-DSL (HCL, Helm) → embedded-scripting all into one thing: real Aether, type-checked, sandboxable, with the full stdlib available when the operator needs it.\n\n```aether\nimport avnserver\n\nmain() {\n    avnserver.serve {\n        host(\"127.0.0.1\")\n        port(9990)\n        superuser_token(env(\"SUPER_TOKEN\"))   // computed at config time\n        repo(\"alpha\", \"/srv/alpha\")\n        repo(\"beta\",  \"/srv/beta\")\n    }\n}\n```\n\nSame file is config, validation, conditional logic, and the entry point. No second parser, no second type system, no template language. Sandboxing (`--emit=lib --with=...`, `hide`, `seal except`) keeps it safe to accept untrusted configs as the embedded-DSL case demands. See [Config IS Code](docs/config-is-code.md) for the full progression (YAML → HCL → Pulumi → here) and library-author recipe.\n\n## Runtime Configuration\n\nWhen embedding the Aether runtime in a C application, configure optimizations at startup:\n\n```c\n#include \"runtime/aether_runtime.h\"\n\nint main() {\n    // Auto-detect CPU features and enable optimizations\n    aether_runtime_init(4, AETHER_FLAG_AUTO_DETECT);\n\n    // Or manually configure\n    aether_runtime_init(4,\n        AETHER_FLAG_LOCKFREE_MAILBOX |\n        AETHER_FLAG_ENABLE_SIMD |\n        AETHER_FLAG_ENABLE_MWAIT\n    );\n\n    // Your actor system runs here\n\n    return 0;\n}\n```\n\nAvailable flags:\n- `AETHER_FLAG_AUTO_DETECT` - Detect CPU features and enable optimizations\n- `AETHER_FLAG_LOCKFREE_MAILBOX` - Use lock-free SPSC mailboxes\n- `AETHER_FLAG_ENABLE_SIMD` - AVX2 vectorization for batch operations\n- `AETHER_FLAG_ENABLE_MWAIT` - MWAIT-based idle (x86 only)\n- `AETHER_FLAG_VERBOSE` - Print runtime configuration\n\n## Optimization Tiers\n\nThe runtime employs a tiered optimization strategy:\n\n**TIER 0 - Platform Capabilities (compile-time):**\n- `AETHER_HAS_THREADS` — pthreads/Win32 threads (auto-detected; disabled on WASM/embedded)\n- `AETHER_HAS_ATOMICS` — C11 stdatomic (fallback: volatile for single-threaded)\n- `AETHER_HAS_FILESYSTEM` / `AETHER_HAS_NETWORKING` — stdlib feature gates\n- `AETHER_HAS_SIMD` / `AETHER_HAS_NUMA` / `AETHER_HAS_AFFINITY` — hardware feature gates\n- Override any flag with `-DAETHER_NO_\u003cFEATURE\u003e` (e.g. `-DAETHER_NO_THREADING`)\n\n**TIER 1 - Always Enabled:**\n- Actor pooling (reduces allocation overhead)\n- Direct send for same-core actors (bypasses queues)\n- Adaptive batching (adjusts batch size dynamically)\n- Message coalescing (combines small messages)\n- Thread-local message pools\n\n**TIER 2 - Auto-Detected:**\n- SIMD batch processing (requires AVX2/NEON)\n- MWAIT idle (requires x86 MONITOR/MWAIT)\n- CPU core pinning (OS-dependent)\n\n**TIER 3 - Opt-In:**\n- Lock-free mailbox (better under contention)\n- Message deduplication (prevents duplicate processing)\n\n## Documentation\n\n- [Getting Started Guide](docs/getting-started.md) - Installation and first steps\n- [Language Tutorial](docs/tutorial.md) - Learn Aether syntax and concepts\n- [Language Reference](docs/language-reference.md) - Complete language specification\n- [Standard Library Reference](docs/stdlib-reference.md) - Full stdlib surface\n- [HTTP Server](docs/http-server.md) - TLS, HTTP/2, middleware, health probes, metrics, graceful shutdown\n- [Reverse Proxy](docs/http-reverse-proxy.md) - `std.http.proxy` upstream pool, load balancing, health, cache, circuit breaker\n- [HTTP Record/Replay (VCR)](docs/http-vcr.md) - `std.http.server.vcr` Servirtium-format record/replay for HTTP tests\n- [Install Layout](docs/install-layout.md) - What ships in `~/.aether`, MANIFEST format, downstream-link contract\n- [C Interoperability](docs/c-interop.md) - Using C libraries and the `extern` keyword\n- [Architecture Overview](docs/architecture.md) - Runtime and compiler design\n- [Memory Management](docs/memory-management.md) - defer-first manual model, arena allocators\n- [Structured Concurrency](docs/structured-concurrency.md) - Proposal: supervision trees + capability-scoped spawn/send (not yet shipped)\n- [Runtime Optimizations](docs/runtime-optimizations.md) - Performance techniques\n- [Cross-Language Benchmarks](benchmarks/cross-language/README.md) - Comparative performance analysis\n- [Docker Setup](docker/README.md) - Container development environment\n\n## Development\n\n### Running Tests\n\n```bash\n# Runtime C test suite\nmake test\n\n# Aether source tests\nmake test-ae\n\n# All tests\nmake test-all\n\n# Build all examples\nmake examples\n```\n\n### Testing\n\n```bash\n# Full CI suite (8 steps, -Werror) — runs on your current platform\nmake ci\n\n# Unit tests only (215 tests)\nmake test\n\n# Integration + regression .ae tests (463 tests)\nmake test-ae\n\n# Build all examples (89 programs)\nmake examples\n\n# Full CI + Valgrind + ASan in Docker (Linux)\nmake docker-ci\n```\n\n### Cross-Platform Testing\n\n**CI runs automatically on:** Linux (GCC + Clang), macOS (ARM64 + x86_64), Windows (MinGW/MSYS2)\n\n```bash\n# Cooperative scheduler (no Docker needed)\nmake ci-coop\n\n# Windows cross-compile syntax check (requires mingw-w64 or Docker)\nmake ci-windows              # needs: brew install mingw-w64\nmake docker-ci-windows       # or use Docker\n\n# WebAssembly (requires Docker with Emscripten)\nmake docker-ci-wasm\n\n# ARM embedded syntax check (requires Docker with arm-none-eabi-gcc)\nmake docker-ci-embedded\n\n# All portability checks (coop + WASM + embedded)\nmake ci-portability\n```\n\n**`make ci` tests your current OS only.** No OS can locally test another OS natively — macOS cannot be virtualized on Linux/Windows, Windows build+run requires MSYS2. GitHub Actions CI automatically tests all 5 platform targets (Linux GCC, Linux Clang, macOS ARM64, macOS x86_64, Windows MinGW) on every PR. Docker targets (`docker-ci-windows`, `docker-ci-wasm`, `docker-ci-embedded`) provide cross-compilation syntax checking from any host.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the full pre-PR checklist.\n\n### Running Benchmarks\n\n```bash\n# Run cross-language benchmark suite with interactive UI\nmake benchmark\n# Open http://localhost:8080 to view results\n\n```\n\nThe benchmark runner is written in Aether (`run_benchmarks.ae`), dogfooding the stdlib. It compiles and runs all 11 languages, parses output, and writes JSON results.\n\n## Sibling Projects\n\nThe Aether ecosystem includes downstream consumers that live in their\nown repos and release independently:\n\n- **[aether-ui](https://github.com/aether-lang-org/aether-ui)** —\n  Cross-platform widget toolkit (GTK4 on Linux, AppKit on macOS, Win32\n  on Windows) with an AetherUIDriver HTTP test server for headless\n  integration testing. Previously shipped as `contrib/aether_ui/` in\n  this repo; spun out so it can iterate on its own cadence.\n- **[aeb](https://github.com/aether-lang-org/aeb)** — Build system for\n  multi-package Aether projects. Reads `share/aether/MANIFEST` (the\n  authoritative list of link-suitable runtime/stdlib `.c` files) and\n  dispatches per-package builds with cache reuse and incremental\n  relinking.\n\nIf you're adding to Aether and the change isn't a runtime / compiler /\nstdlib concern, the right home may be one of the siblings above. Both\nrepos consume Aether the same way external users do — `import` against\nthe installed `share/aether/` tree plus `$(ae cflags)` for the link\nline — so they're useful references for downstream integration shapes.\n\n## Status\n\nAether is under active development. The compiler, runtime, and standard library are functional and tested.\n\n## Contributing\n\nContributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n**Areas of interest:**\n- Runtime optimizations\n- Standard library expansion\n- Documentation and examples\n\n## Supporting Aether\n\nAether is free and open source, built and maintained in personal time. CI runners, cross-platform testing infrastructure, and future project hosting cost real money.\n\nIf Aether is useful to you, consider [sponsoring the project on GitHub](https://github.com/sponsors/nicolasmd87). Every contribution goes directly into development and infrastructure.\n\n[![Sponsor](https://img.shields.io/badge/Sponsor-Aether-blue?logo=github-sponsors)](https://github.com/sponsors/nicolasmd87)\n\n## Acknowledgments\n\nAether draws inspiration from:\n- **Erlang/OTP** — Actor model, message passing semantics\n- **Go** — Pragmatic tooling, simple concurrency primitives\n- **Rust** — Systems programming practices, zero-cost abstractions\n- **Pony** — Actor-based type safety concepts and object-capability model\n- **Smalltalk / Ruby / Groovy** — Block / closure ergonomics: trailing-block builders, `do |x| … end` syntax, and DSL-shaped APIs where the closure is the configuration\n\n## License\n\nMIT License. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faether-lang-org%2Faether","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faether-lang-org%2Faether","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faether-lang-org%2Faether/lists"}