ADR-0027: Hold a union as its object, or as a tuple of a tag and a slot per member¶
Status¶
Accepted
Date¶
2026-11-13
Context¶
ADR-0022 decided how TyPy holds a union such as int | str (TYP-14): a
union whose members are all objects is the object's address, and any
other union is a tag word followed by the value, in as many bytes as its
largest member takes, the members overlapping.
Unions of objects are built as ADR-0022 decided. Building the overlapped
layout for the other unions needs a new kind of value in TyIR, in code
generation and in the runtime: one whose object fields are counted, copied
and released according to its tag, since the same bytes hold an int
word for one tag and an object's address for another.
TyPy already has a value whose fields are counted by their types: the
tuple, held by value with its items in place. Code generation copies and
releases a tuple field by field; the runtime stores a tuple in a list, a
set or a dict through its descriptor, and counting passes over a null
address and an inline int word. An optional tuple is already held as a
tuple of a presence flag and the tuple (ADR-0011).
Options considered¶
- Overlapped members, as ADR-0022 decided. A tag word, then the largest member's bytes. Every copy, release and store switches on the tag, in code generation and in each runtime function that handles an item.
- A tuple of the tag and one slot for each member. The union is a
tuple
(tag, slot 0, slot 1, ...): the slot the tag names holds the value, and every other slot holds the value that counting passes over, the null address, theint0,0.0orFalse. The tuple is copied, released and stored as any tuple is; only the operations that read the value switch on the tag. - Box value members. Every union is an object, an
intmember a heap object of its own. ADR-0022 refused this for the allocation each storedintcosts.
Decision¶
TyPy uses option 2 for a union with a member held by value, and keeps ADR-0022's decision for a union of objects. This record supersedes ADR-0022 and restates the whole decision.
- Normal form. A union is a set of members, so
int | strandstr | intare one type. A member that another member accepts is dropped, and a union of one member is that member. - A union of objects is the object's address, held as the class every member derives from when they share one, and otherwise as an object whose header says what it is.
- Any other union is a TyIR tuple marked as a union: an
inttag, the member's position in the normal form, then one slot for each member.Nonemakes the union optional, held as ADR-0011 holds an optional tuple: a presence flag beside the union. - Reading the value switches on the tag: narrowing reads the slot it
names, and
str,repr, truth,type()and an operation checked for each member run the branch for the tag. - Containers. The runtime gains an item kind for a union, whose descriptor is the union's tuple. It writes, compares, hashes and tests the item as the member its tag names: two members that are numbers compare by value, and two members of other types are not equal, as in CPython.
Consequences¶
- A union with a value member takes eight bytes for the tag and eight
for each member it can hold, more than the overlapped layout: an
int | strtakes 24 bytes in place of 16. - Code generation and counting need nothing new: the union is a tuple. Only the operations that read the value, and the runtime's item kind, know the tag.
- Storing an
intin anint | strallocates nothing. - A later change may overlap the slots without changing the language: the layout is internal to TyIR and the runtime.
Related requirements¶
TYP-07, TYP-14, ADR-0009, ADR-0011, ADR-0012, ADR-0021, ADR-0022.