Introduction

This book is the primary reference for the Eter programming language.

It does not serve as an introduction to the language. Background familiarity with the language is assumed.

Additionally, this book does not assume you are reading it sequentially. Each chapter generally can be read standalone, but will cross-link to other chapters for facets of the language they refer to, but do not discuss.

Note

For known bugs and omissions in this book, see our GitHub issues. If you see a case where the compiler behavior and the text here do not agree, file an issue so we can think about which is correct.

Eter releases

Caution

TODO: add release information here once we have a release.

Conventions

Like all technical books, this book has certain conventions in how it displays information. These conventions are documented here.

• Statements that define a term contain that term in italics. Whenever that term is used outside of that chapter, it is usually a link to the section that has this definition.

  An example term is an example of a term being defined.

• Notes that contain useful information about the state of the book or point out useful, but mostly out of scope, information are in note blocks.

  Note

  This is an example note.

• Example blocks show an example that demonstrates some rule or points out some interesting aspect. Some examples may have hidden lines which can be viewed by clicking the eye icon that appears when hovering or tapping the example.

  Tip

  This is a code example.

  #![allow(unused)]
  fn main() {
  println!("hello world");
  }

• Warnings that show unsound behavior in the language or possibly confusing interactions of language features are in a special warning box.

  Warning

  This is an example warning.

• Code snippets inline in the text are inside <code> tags.

  Longer code examples are in a syntax highlighted box that has controls for copying, executing, and showing hidden lines in the top right corner.

  // This is a hidden line.
  fn main() {
      println!("This is a code example");
  }

  All examples are written for the latest edition unless otherwise stated.

• Informational blocks that contain useful information about the language, but are not normative, are in informational boxes.

  Important

  This is an important block.

• Caution blocks that contain information about unsound behavior in the language or possibly confusing interactions of language features are in a special caution box.

  Caution

  This is a caution block.

• The grammar and lexical productions are described in the Notation chapter.

Contributing

We welcome contributions of all kinds.

You can contribute to this book by opening an issue or sending a pull request to the Eter repository. If this book does not answer your question, and you think its answer is in scope of it, please do not hesitate to file an issue. Knowing what people use this book for the most helps direct our attention to making those sections the best that they can be. And of course, if you see anything that is wrong or is non-normative but not specifically called out as such, please also file an issue.

Lexical structure

A sequence of Unicode characters is translated into a sequence of tokens. The following rules apply during translation:

1. Comments are treated as though they are a single space U+20.
2. Spaces are ignored unless they appear between the opening and closing delimiters of a character or string literal. Unicode characters with the “White_Space” property are recognized as spaces.
3. New-line delimiters are ignored unless they appear between the opening and closing delimiters of a character or string literal. Unicode characters with the “Line_Break” property are recognized as new-line delimiters.

Comments

The character sequence // starts a single-line comment, which terminates immediately before the next new-line delimiter.

The character sequences /* and */ are multiline comment opening and closing delimiters, respectively. A multiline comment opening delimiter starts a comment that terminates immediately after a matching closing delimiter. Each opening delimiter must have a matching closing delimiter. Multiline comments may nest and need not contain any new-line characters.

Note

The character sequences // have no special meaning in a multiline comment. The character sequences /* and */ have no special meaning in a single-line comment. The character sequences // and /* have no special meaning in a string literal. String and character literal delimiters have no special meaning in a comment.

Tokens

A token is a terminal symbol of the syntactic grammar. It falls into one of five categories:

Note

The input a << b is translated to a sequence of 4 tokens: identifier, raw-operator, raw-operator, identifier.

Unless otherwise specified, the token recognized at a given lexical position is the one having the longest possible sequence of characters.

Literals

Literals are tokens representing fixed values in the source code. The language supports the following types of literals:

Keywords

Keywords are reserved words that have special meaning in the language. They cannot be used as identifiers. The language defines the following keywords:

Note: Some keywords might be reserved for future use or macro rules.

Identifiers

An identifier is a name used to identify a variable, function, class, module, or other user-defined item.

Identifiers must follow these rules:

1. They must begin with a letter (a-z, A-Z) or an underscore _.
2. Subsequent characters may be letters, digits (0-9), or underscores _.
3. They cannot match one of the reserved keywords.

Operators

Operators are special symbols or combinations of symbols used to perform operations on values or variables.

Delimiters

Delimiters are punctuation characters used to group tokens, separate lists, or define structure.

Type system

Statically sized types

Boolean type

Numeric types

Textual types

Array types

Tensor types

Pointer types

Union types

Tuple types

Static types layout

Dinamically sized types

Struct types

Enum types

View types

Items

Modules

Constant

External block

Use declarations

Functions

Unions

Structs

Enumerations

Statemets and expressions

Statements

Statement terminator

Assignment statements

Item declaration statements

Expression statements

Expressions

Literal expressions

Path expressions (::)

Block expressions

Operator expressions

Grouped expressions

Array and index expressions

Tuple and index expressions

Struct expressions

Call expressions

Field access expressions

Loop expressions

If expressions

Match expressions

-> Includere i match patterns

Return expressions

Underscore expressions

Qualifiers

The language uses a system of annotqualifiers) to explicitly define the memory hierarchy and movement of data across different hardware components. This provides a complete mental model for data management, from CPU RAM to GPU SRAM.

@host

• Hardware: CPU RAM
• Typical Usage: Dataset loading and heavy preprocessing tasks (Pandas-style). This is standard, pageable system memory.

@pinned

• Hardware: CPU RAM (Page-locked / Pinned)
• Typical Usage: Transit buffers used to stream data to GPUs at high bandwidth (e.g., 32GB/s+). Since it cannot be paged out to disk, it allows for faster DMA transfers to the device.

@global

• Hardware: GPU VRAM
• Typical Usage: Storage of model weights, biases, and gradients on a single GPU board. This is the main high-capacity memory on the device.

@sharded

• Hardware: Cluster VRAM (Multi-GPU)
• Typical Usage: Distribution of giant models (e.g., Llama 405B) across 8+ GPUs. It abstracts the partitioned memory across a cluster of devices.

@shared

• Hardware: GPU SRAM (Shared Memory)
• Typical Usage: Ultra high-speed computation inside a kernel (e.g., Tiling). This is the small, fast, on-chip memory shared by threads within the same block.

Memory model

Mutable Value Semantics (MVS)

Immutability

Mutability

Ownership

Use of Pointers (unsafe scopes)

• let ptr<i32>
• let mut ptr<i32>
• let ptr<mut i32>
• let mut ptr<mut i32>

Namespaces

Type namespace

Value namespace

Scopes

Unsafety

Unsafe scopes

unsafe {…}

Unsafe functions

unsafe fn foo() {…}