Struct ClassLayoutBuilder

pub struct ClassLayoutBuilder { /* private fields */ }

Builder for creating ClassLayout metadata entries.

ClassLayoutBuilder provides a fluent API for creating ClassLayout table entries with validation and automatic table management. Class layouts define type-level memory layout characteristics including field alignment boundaries, explicit type sizes, and packing behavior for performance optimization and interoperability scenarios.

Class Layout Model

.NET class layout follows a structured pattern:

• Parent Type: The type definition that this layout applies to
• Packing Size: Field alignment boundary (must be 0 or power of 2)
• Class Size: Explicit type size override (0 for automatic sizing)
• Layout Control: Precise control over type memory characteristics

Layout Types and Scenarios

Class layouts are essential for various memory management scenarios:

• P/Invoke Interop: Matching native C/C++ struct sizes and alignment
• Performance Critical Types: Cache-line alignment and SIMD optimization
• Memory Mapping: Direct memory-mapped structures with fixed sizes
• Platform Compatibility: Consistent layouts across different architectures
• Legacy Compatibility: Matching existing binary format specifications
• COM Interop: Implementing COM interface memory layout requirements

Packing Size Specifications

Packing size controls field alignment boundaries:

• 0: Default packing (typically 8 bytes, platform-dependent)
• 1: Byte alignment (no padding between fields)
• 2: 2-byte alignment (short/char alignment)
• 4: 4-byte alignment (int/float alignment)
• 8: 8-byte alignment (long/double alignment)
• 16: 16-byte alignment (SIMD/SSE alignment)
• 32: 32-byte alignment (AVX alignment)
• 64: 64-byte alignment (cache line alignment)
• 128: 128-byte alignment (maximum allowed)

Class Size Specifications

Class size provides explicit type size control:

• 0: Automatic size calculation based on fields
• Non-zero: Explicit type size override in bytes
• Minimum: Must accommodate all fields within the type
• Maximum: Cannot exceed 256MB (0x10000000 bytes)
• Alignment: Should respect packing size alignment

Examples

let assembly = CilAssembly::new(view);
let mut context = BuilderContext::new(assembly);

// Create layout for a P/Invoke structure with byte packing
let struct_type = Token::new(0x02000001); // TypeDef RID 1

let packed_layout = ClassLayoutBuilder::new()
    .parent(struct_type)
    .packing_size(1) // Byte packing (no padding)
    .class_size(0)   // Automatic size
    .build(&mut context)?;

// Create layout for a performance-critical type with cache-line alignment
let perf_type = Token::new(0x02000002); // TypeDef RID 2

let aligned_layout = ClassLayoutBuilder::new()
    .parent(perf_type)
    .packing_size(64) // Cache line alignment
    .class_size(128)  // Fixed 128-byte size
    .build(&mut context)?;

// Create layout for SIMD-optimized mathematics structure
let simd_type = Token::new(0x02000003); // TypeDef RID 3

let simd_layout = ClassLayoutBuilder::new()
    .parent(simd_type)
    .packing_size(16) // SSE/SIMD alignment
    .class_size(64)   // Fixed 64-byte size for 4x float4
    .build(&mut context)?;

// Create layout for exact native structure matching
let native_type = Token::new(0x02000004); // TypeDef RID 4

let native_layout = ClassLayoutBuilder::new()
    .parent(native_type)
    .packing_size(4)  // 32-bit alignment
    .class_size(24)   // Exact size to match native struct
    .build(&mut context)?;

Implementations

impl ClassLayoutBuilder

pub fn new() -> Self

Creates a new ClassLayoutBuilder.

Returns

A new crate::metadata::tables::classlayout::ClassLayoutBuilder instance ready for configuration.

pub fn packing_size(self, packing: u16) -> Self

Sets the field alignment boundary (packing size).

The packing size controls the alignment boundary for fields within the type, affecting both field placement and overall type size. This directly impacts memory layout, performance characteristics, and interoperability requirements.

Packing size constraints:

• Must be 0 or a power of 2: 0, 1, 2, 4, 8, 16, 32, 64, 128
• 0 means default: Platform-dependent default alignment (typically 8 bytes)
• Maximum value: 128 bytes (larger values are not supported)
• Performance impact: Smaller values reduce memory usage but may hurt performance
• Interop requirement: Must match native structure alignment expectations

Common packing scenarios:

• 1: Tight packing for network protocols and file formats
• 4: Standard 32-bit platform alignment
• 8: Standard 64-bit platform alignment and double precision
• 16: SIMD/SSE optimization alignment
• 32: AVX optimization alignment
• 64: Cache line alignment for performance-critical structures

Arguments

• packing - The field alignment boundary in bytes (0 or power of 2, max 128)

Returns

Self for method chaining.

pub fn class_size(self, size: u32) -> Self

Sets the explicit type size override.

The class size provides explicit control over the total size of the type, overriding automatic size calculation based on field layout. This is essential for exact native structure matching and performance optimization scenarios.

Class size considerations:

• 0 means automatic: Let the runtime calculate size based on fields
• Non-zero override: Explicit size specification in bytes
• Minimum requirement: Must accommodate all fields and their alignment
• Maximum limit: Cannot exceed 256MB (0x10000000 bytes)
• Alignment respect: Should be aligned to packing size boundary
• Padding inclusion: Size includes any trailing padding needed

Size specification scenarios:

• Native matching: Exact size to match C/C++ structures
• Performance tuning: Specific sizes for cache optimization
• Memory mapping: Fixed sizes for memory-mapped data structures
• Protocol compliance: Exact sizes for network and file protocols
• Legacy compatibility: Maintaining compatibility with existing layouts

Arguments

• size - The explicit type size in bytes (0 for automatic, max 256MB)

Returns

Self for method chaining.

pub fn parent(self, parent: Token) -> Self

Sets the parent type that this layout applies to.

The parent must be a valid TypeDef token that references a type definition in the current assembly. This establishes which type will have this layout specification applied to control its memory characteristics.

Parent type requirements:

• Valid Token: Must be a properly formatted TypeDef token (0x02xxxxxx)
• Existing Type: Must reference a type that has been defined
• Layout Compatible: Type must support explicit layout specification
• Single Layout: Each type can have at most one ClassLayout entry
• Class or Struct: Only applies to classes and value types, not interfaces

Type categories that can have layout:

• Value Types: Structs with explicit memory layout control
• Reference Types: Classes with specific layout requirements
• P/Invoke Types: Types used in native interop scenarios
• Performance Types: Types optimized for specific performance characteristics
• Protocol Types: Types matching external data format specifications

Arguments

• parent - A TypeDef token pointing to the type receiving this layout

Returns

Self for method chaining.

pub fn build(self, context: &mut BuilderContext) -> Result<Token>

Builds the class layout and adds it to the assembly.

This method validates all required fields are set, verifies the constraints are met, creates the raw class layout structure, and adds it to the ClassLayout table with proper token generation and validation.

Arguments

• context - The builder context for managing the assembly

Returns

A crate::metadata::token::Token representing the newly created class layout, or an error if validation fails or required fields are missing.

Errors

• Returns error if packing_size is not set
• Returns error if class_size is not set
• Returns error if parent is not set
• Returns error if parent is not a valid TypeDef token
• Returns error if parent RID is 0 (invalid RID)
• Returns error if packing_size is not 0 or a power of 2
• Returns error if packing_size exceeds 128 bytes
• Returns error if class_size exceeds 256MB limit
• Returns error if table operations fail

Trait Implementations

impl Default for ClassLayoutBuilder

fn default() -> Self

Returns the “default value” for a type.