Layout

struct Layout[T: AnyType]

Describes the shape of a memory allocation for elements of type T.

A Layout bundles the count of elements and the alignment of the allocation into a single value. Passing a Layout to alloc and free keeps the size and alignment requirements explicit and co-located at every call site, preventing mismatches between allocation and deallocation.

Example:

from std.memory.alloc import alloc, free, Layout

# Allocate room for 8 Int32 values with default alignment.
var layout = Layout[Int32](count=8)
var ptr = alloc(layout)
# ... use ptr ...
free(ptr, layout)

Parameters

• ​T (AnyType): The element type the layout describes.

Implemented traits

AnyType, Copyable, ImplicitlyCopyable, ImplicitlyDestructible, Movable, RegisterPassable, TrivialRegisterPassable, Writable

Methods

__init__

__init__(*, count: Int) -> Self

Initializes a Layout with the given element count and a default alignment.

Args:

• ​count (Int): Number of elements of type T to describe.

__init__(*, count: Int, alignment: Int) -> Self

Initializes a Layout with the given element count and alignment.

This method will abort if the alignment is invalid.

Args:

• ​count (Int): Number of elements of type T to describe.
• ​alignment (Int): Byte alignment of the allocation. Must be a power of two.

aligned

static aligned[alignment: Int](*, count: Int) -> Self

Initializes a Layout with the given element count and comptime alignment.

Unlike Layout[T](count, alignment), this validates alignment at compile time.

Parameters:

• ​alignment (Int): Byte alignment of the allocation. Must be a power of two.

Args:

• ​count (Int): Number of elements of type T to describe.

Returns:

Self: A Layout with the specified count and alignment.

single

static single() -> Self

Creates a Layout for exactly one element of type T.

Example:

from std.memory.alloc import alloc, free, Layout

var layout = Layout[Int64].single()
var ptr = alloc(layout)
ptr.init_pointee_move(0)
free(ptr, layout)

Returns:

Self: A Layout with count equal to 1 and default alignment.

as_byte_layout

as_byte_layout(self) -> Layout[UInt8]

Converts this layout to an equivalent byte-level layout.

Multiplies the element count by size_of[T]() to express the same allocation in terms of raw bytes, preserving the alignment.

Returns:

Layout[UInt8]: A Layout[Byte] whose count is self.count() * size_of[T]() and whose alignment matches self.alignment().

alignment

alignment(self) -> Int

Returns the alignment of the allocation described by this layout.

Returns:

Int: The byte alignment.

count

count(self) -> Int

Returns the number of elements described by this layout.

Returns:

Int: The element count passed at construction time.

write_to

write_to(self, mut writer: T)

Writes a human-readable representation of this layout to writer.

Args:

• ​writer (T): The writer to write to.

write_repr_to

write_repr_to(self, mut writer: T)

Writes a debug representation of this layout to writer.

Args:

• ​writer (T): The writer to write to.

is_valid_alignment

static is_valid_alignment(alignment: Int) -> Bool

Reports whether alignment is a valid alignment for Layout[T].

An alignment is valid when it is a power of two and is at least the natural alignment of T (align_of[T]()). Under-aligning T would violate its layout requirements, so requested alignments must meet or exceed the natural alignment.

Example:

from std.memory.alloc import Layout

var ok = Layout[Int32].is_valid_alignment(64)  # True (over-aligned)
var not_pow2 = Layout[Int32].is_valid_alignment(33)  # False
var too_small = Layout[Int32].is_valid_alignment(4)  # False

Args:

• ​alignment (Int): The candidate byte alignment to check.

Returns:

Bool: True if alignment is a power of two and is no smaller than align_of[T](), otherwise False.