Struct TesseraRuntime

pub struct TesseraRuntime {
    pub component_tree: ComponentTree,
    pub window_size: [u32; 2],
    pub cursor_icon_request: Option<CursorIcon>,
    /* private fields */
}

Central runtime state container for the Tessera UI framework.

The TesseraRuntime holds all global state and side effects that need to be shared across the entire application. This includes the component tree structure, window properties, and user interface state that persists across frame updates.

Design Philosophy

The runtime follows these key principles:

• Single Source of Truth: All shared state is centralized in one location
• Thread Safety: Safe concurrent access through read-write locks
• Lazy Initialization: Runtime is created only when first accessed
• Minimal Overhead: Optimized for frequent reads and occasional writes

Lifecycle

The runtime is automatically initialized on first access and persists for the entire application lifetime. It cannot be manually destroyed or recreated.

Fields

All fields are public to allow direct access after acquiring the appropriate lock. However, consider using higher-level APIs when available to maintain consistency.

Fields

component_tree: ComponentTree

The hierarchical structure of all UI components in the application.

This tree represents the current state of the UI hierarchy, including component relationships, layout information, and rendering data. The component tree is rebuilt or updated each frame during the UI update cycle.

Thread Safety

While the runtime itself is thread-safe, individual operations on the component tree may require coordination to maintain consistency during parallel processing phases.

window_size: [u32; 2]

Current window dimensions in physical pixels.

This array contains [width, height] representing the current size of the application window. These values are updated automatically when the window is resized and are used for layout calculations and rendering.

Coordinate System

• Values are in physical pixels (not density-independent pixels)
• Origin is at the top-left corner of the window
• Both dimensions are guaranteed to be non-negative

cursor_icon_request: Option<CursorIcon>

Cursor icon change request from UI components.

Components can request cursor icon changes by setting this field during their update cycle. The windowing system will apply the requested cursor icon if present, or use the default cursor if None.

Lifecycle

This field is typically:

1. Reset to None at the beginning of each frame
2. Set by components during event handling or state updates
3. Applied by the windowing system at the end of the frame

Priority

If multiple components request different cursor icons in the same frame, the last request takes precedence. Components should coordinate cursor changes or use a priority system if needed.

Implementations

impl TesseraRuntime

pub fn read() -> RwLockReadGuard<'static, Self>

Acquires shared read access to the runtime state.

This method returns a read guard that allows concurrent access to the runtime data from multiple threads. Multiple readers can access the runtime simultaneously, but no writers can modify the state while any read guards exist.

Blocking Behavior

This method will block the current thread if a write lock is currently held. It will return immediately if no write locks are active, even if other read locks exist.

Usage

use tessera_ui::TesseraRuntime;

// Access runtime data for reading
let runtime = TesseraRuntime::read();
let [width, height] = runtime.window_size;
println!("Window size: {}x{}", width, height);
// Lock is automatically released when `runtime` goes out of scope

Performance

Read locks are optimized for high-frequency access and have minimal overhead when no write contention exists. Prefer read locks over write locks whenever possible to maximize parallelism.

Deadlock Prevention

To prevent deadlocks:

• Always acquire locks in a consistent order
• Keep lock scopes as narrow as possible
• Avoid calling other locking functions while holding a lock

Returns

A [RwLockReadGuard] that provides read-only access to the runtime state. The guard automatically releases the lock when dropped.

pub fn write() -> RwLockWriteGuard<'static, Self>

Acquires exclusive write access to the runtime state.

This method returns a write guard that provides exclusive access to modify the runtime data. Only one writer can access the runtime at a time, and no readers can access the state while a write lock is held.

Blocking Behavior

This method will block the current thread until all existing read and write locks are released. It guarantees exclusive access once acquired.

Usage

use tessera_ui::TesseraRuntime;

// Modify runtime state
{
    let mut runtime = TesseraRuntime::write();
    runtime.window_size = [1920, 1080];
    runtime.cursor_icon_request = Some(winit::window::CursorIcon::Pointer);
} // Lock is automatically released

Performance Considerations

Write locks are more expensive than read locks and should be used sparingly:

• Batch multiple modifications into a single write lock scope
• Release write locks as quickly as possible
• Consider if the operation truly requires exclusive access

Deadlock Prevention

The same deadlock prevention guidelines apply as with read():

• Acquire locks in consistent order
• Minimize lock scope duration
• Avoid nested locking operations

Returns

A [RwLockWriteGuard] that provides exclusive read-write access to the runtime state. The guard automatically releases the lock when dropped.

pub fn on_minimize(&mut self, callback: impl Fn(bool) + Send + Sync + 'static)

Registers a per-frame callback for minimize state changes. Components should call this every frame they wish to be notified.

pub fn on_close(&mut self, callback: impl Fn() + Send + Sync + 'static)

Registers a per-frame callback for window close event. Components should call this every frame they wish to be notified.

pub fn clear_frame_callbacks(&mut self)

Clears all per-frame registered callbacks. Must be called by the event loop at the beginning of each frame.

pub fn trigger_minimize_callbacks(&self, minimized: bool)

Triggers all registered callbacks (global and per-frame). Called by the event loop when a minimize event is detected.

pub fn trigger_close_callbacks(&self)

Triggers all registered callbacks (global and per-frame) for window close event. Called by the event loop when a close event is detected.

Trait Implementations

impl Default for TesseraRuntime

fn default() -> TesseraRuntime

Returns the “default value” for a type.