Info tables¶
AIHC uses an info table to describe each type of object in managed memory. An object header ordinarily points to one info table. Thus, an object does not contain a copy of its run-time description.
Generated info tables are immutable. The collector temporarily uses the header as a forwarding address when it moves an object. The run-time system marks a thunk under evaluation with bit 0 of its header. The header still points to the thunk table.
The AMD64, ARM64, LLVM, and WebAssembly backends use the same info table model.
They use the common AihcInfo layout from the native run-time system.
Table fields¶
Each info table contains these fields:
| Field | Purpose |
|---|---|
identity |
Identifies the function or the saturated constructor. |
field_is_pointer |
Points to a byte map that identifies managed pointers. For an object that requires arguments, the map also includes the fields that the arguments will supply. |
next |
Points to the table for the next application stage. |
backend_entry |
Gives the entry address that has the backend calling convention. |
srt |
Points to the static reference table of the code, or is null. |
field_count |
Gives the number of payload fields in the object. One byte: an object has at most 255 fields. |
remaining_arity |
Gives the number of arguments that the object still requires. One byte: a function takes at most 255 arguments. |
frame_kind |
Identifies a continuation frame for stack unwind operations. |
object_kind |
Identifies a node, closure, thunk, partial constructor, or special run-time object. |
needs_eval |
Is 1 for a thunk, 2 for an indirection, and 0 for a value. A thunk under evaluation keeps the value 1. |
constructor_index |
Gives the index of a constructor in its data declaration, from zero. It is 0 for other objects. Two bytes: a data type has at most 65536 constructors. |
The garbage collector uses field_count and field_is_pointer to find managed pointers.
It reads only the first field_count bytes of the map.
The application code uses remaining_arity and next to apply one source argument.
The inline evaluation check uses only needs_eval to find a value or an indirection.
The run-time evaluation code uses object_kind and backend_entry to enter an object.
Exception code uses frame_kind to identify continuation frames.
A case with four constructor alternatives or more uses constructor_index to select an alternative.
A case with fewer alternatives compares identity with each constructor table.
One source argument can use more than one machine field.
For this reason, two adjacent tables can have field counts that differ by more than one.
The map of a table gives the layout of the fields that the next source argument supplies.
The run-time system reads the map at index field_count to find the kind of an arriving field.
Application stages¶
A function has one info table for each required application stage.
An underapplication copies the object and its fields into a new object.
The new object header points to the next table.
An application that supplies all remaining arguments does not make this copy.
It calls the backend entry of the object instead.
The table sequence records these changes:
The backend entry of a stage takes all remaining arguments of that stage.
One application supplies a maximum of four argument groups.
Thus, a stage has a backend entry only when one to four argument groups remain.
The last table requires one argument group and has no next value.
No object holds all the arguments, so no table describes that object.
A saturated call of a known function calls the generated code directly.
Use the example below to see each stage of a function. Change the number of supplied arguments with the slider. Change the representation of an argument to see how the field layout changes.
Enable JavaScript to use the interactive example.
A constructor works differently.
It has two tables however many arguments it takes: one for the saturated node,
and one shared by every stage that still wants arguments.
An unsaturated constructor object stores in its first field the count of the
fields it holds, and its own fields follow from the second.
The shared table gives the saturated table as its next value, which is where
the run-time system reads the full width and the complete pointer map.
The slots an unsaturated constructor has filled are a prefix of the slots the
saturated one holds, so one pointer map serves both.
A saturated constructor is a data node, does not enter code, and stores no
count.
Enable JavaScript to use the interactive example.
Suspended function example¶
Consider a suspended call that captures x and y:
AIHC can represent this suspended call as a GRIN thunk for the generated total function.
Field 0 of the object is the owner word, and the captured values follow it.
The run-time system will keep the state of an evaluation in the owner word.
Its table has the following logical values:
| Field | Value |
|---|---|
identity |
The generated total function. |
field_is_pointer |
One byte of 0 for the owner word, then one byte for x and one byte for y. |
next |
Null. |
backend_entry |
The backend entry for total. |
srt |
Null. |
field_count |
3 |
remaining_arity |
0 |
frame_kind |
No frame. |
object_kind |
Thunk. |
needs_eval |
1 |
The pointer map depends on the run-time representation of x and y.
For example, a lifted value has a pointer byte of 1.
An Int# value has a pointer byte of 0.
When code evaluates total, it reads the needs_eval byte from the table.
The byte is 1, so the code calls the run-time evaluation code.
After the update, the object is an indirection and the byte is 2.
The code then follows the indirection to the result without a call.
That code reads the thunk kind and uses the backend entry to call the generated function.
During evaluation, the run-time system pushes an update frame and sets bit 0 of the header.
The header still points to the thunk table.
A second evaluation sees this bit and handles the object as a blackhole.
After evaluation, the run-time system changes the thunk into an indirection to the result.
It writes the result into the owner word.
Use the example below to see the thunk before, during, and after evaluation.
Enable JavaScript to use the interactive example.
Constructor example¶
Consider this constructor:
Pair has arity two.
AIHC can represent Pair, Pair first, and Pair first second as managed objects.
The backend supplies two info tables:
| Table | Object kind | field_count |
next |
|---|---|---|---|
Pair partial |
Partial constructor | 2 | The saturated table. |
Pair saturated |
Node | 2 | Null. |
Pair and Pair first both use the partial table and differ only in the count
they store:
| Object | Stored count | Stored fields |
|---|---|---|
Pair |
0 | 0 |
Pair first |
1 | 1 |
Pair first second |
None | 2 |
Both tables use the saturated constructor table as their identity value.
This stable identity lets case code compare a value with the Pair constructor.
Both tables also give the complete pointer map for both constructor fields.
Constructor application uses the common slow application path. This path allocates the object for the next stage and copies the stored fields. An application that fills the last field allocates a saturated node instead, which drops the stored count. The final object is a data node, so its entry addresses are null.
Nullary constructors have only the saturated table. The backend also makes an implicit static object for each nullary constructor.
Backend differences¶
The backends do not change the field meanings or the application sequence. They change the table encoding and the backend entry implementation.
AMD64¶
The AMD64 backend emits each table in read-only data.
The backend_entry field points to an entry adapter.
The run-time system provides shared adapters for objects whose fields and supplied values are all pointers, with up to eight fields and one supplied value.
The compiler emits a small adapter for each other directly enterable object.
Generated control code reads this field and jumps to the adapter.
ARM64¶
The ARM64 backend uses the same table contents as the AMD64 backend. It emits the tables and entry adapters with ARM64 sections, symbols, and calling conventions.
LLVM¶
The LLVM backend emits constant values of the %AihcInfo type.
It puts a tailcc adapter in backend_entry for an enterable object.
It emits only the constructor tables that the current compilation unit requires.
Linked constructor table names keep constructor identities equal across compilation units.
WebAssembly¶
The WebAssembly backend emits the same fields in WebAssembly assembly data. Its pointers are 32 bits and its counts, kind values, and flags are one byte each. Thus, its table is 28 bytes instead of the 48-byte table on 64-bit native targets.
WebAssembly calls require a compatible function type.
Its run-time adapter converts backend_entry to the required function type.
The adapter then transfers control through the WebAssembly trampoline.
The backend entry gives the fast path for generated code.