Module app

Expand description

App extensions, context, events and commands API.

§Runtime

A typical app instance has two processes, the initial process called the app-process, and a second process called the view-process. The app-process implements the event loop and updates, the view-process implements the platform integration and renderer, the app-process controls the view-process, most of the time app implementers don’t interact directly with it, except at the start where the view-process is spawned.

The reason for this dual process architecture is mostly for resilience, the unsafe interactions with the operating system and graphics driver are isolated in a different process, in case of crashes the view-process is respawned automatically and all windows are recreated. It is possible to run the app in a single process, in this case the view runs in the main thread and the app main loop in another.

§View-Process

To simplify distribution the view-process is an instance of the same app executable, the view-process crate injects their own “main” in the zng::env::init! call, automatically taking over the process if the executable spawns as a view-process.

On the first instance of the app executable the init only inits the env and returns, the app init spawns a second process marked as the view-process, on this second instance the init call never returns, for this reason the init must be called early in main, all code before the init call runs in both the app and view processes.

[dependencies]
zng = { version = "0.19.2", features = ["view_prebuilt"] }

use zng::prelude::*;

fn main() {
    app_and_view();
    zng::env::init!(); // init only returns if it is not called in the view-process.
    app();
}

fn app_and_view() {
    // code here runs in the app-process and view-process.
}

fn app() {
    // code here only runs in the app-process.

    APP.defaults().run(async {
        // ..
    })
}

§Same Process

You can also run the view in the same process, this mode of execution is slightly more efficient, but your app will not be resilient to crashes caused by the operating system or graphics driver, the app code will also run in a different thread, not the main.

use zng::prelude::*;

fn main() {
    zng::env::init!();
    zng::view_process::prebuilt::run_same_process(app);
}

fn app() {
    // code here runs in a different thread, the main thread becomes the view.
    APP.defaults().run(async {
        // ..
    })
}

Note that you must still call init! as it also initializes the app metadata and directories.

§Headless

The app can also run headless, where no window is actually created, optionally with real rendering. This mode is useful for running integration tests, or for rendering images.

use zng::prelude::*;

let mut app = APP.defaults().run_headless(/* with_renderer: */ false);
app.run_window(async {
    Window! {
        child = Text!("Some text");
        auto_size = true;

        render_mode = window::RenderMode::Software;
        frame_capture_mode = window::FrameCaptureMode::Next;

        on_frame_image_ready = async_hn!(|args| {
            if let Some(img) = args.frame_image {
                // if the app runs with `run_headless(/* with_renderer: */ true)` an image is captured
                // and saved here.
                img.save("screenshot.png").await.unwrap();
            }

            // close the window, causing the app to exit.
            WINDOW.close();
        });
    }
});

You can also run multiple headless apps in the same process, one per thread, if the crate is build using the "multi_app" feature.

§App Extension

Apps can be extended to provide new services and events, in fact all default services and events are implemented as extensions loaded by APP.defaults(). The app extension API is AppExtension. Usually extensions are named with suffix Manager, but that is not a requirement.

use zng::{
    APP,
    app::{AppExtended, AppExtension},
};

#[derive(Default)]
pub struct HelloManager {}
impl AppExtension for HelloManager {
    fn init(&mut self) {
        println!("Hello init!");
    }

    fn update_preview(&mut self) {
        println!("Hello before UI!");
    }

    fn update(&mut self) {
        println!("Hello after UI!");
    }
}

pub fn app() -> AppExtended<impl AppExtension> {
    APP.defaults().extend(HelloManager::default())
}

§Services

App services are defined by convention, there is no service trait or struct. Proper service implementations follow these rules:

§App services are an unit struct named like a static

This is because services are a kind of singleton. The service API is implemented as methods on the service struct.

#[expect(non_camel_case_types)]
pub struct SCREAMING_CASE;
impl SCREAMING_CASE {
    pub fn state(&self) -> Var<bool> {
    }
}

Note that you need to suppress a lint if the service name has more then one word.

Service state and config methods should prefer variables over direct values. The use of variables allows the service state to be plugged directly into the UI. Async operations should prefer using ResponseVar<R> over async methods for the same reason.

§App services lifetime is the current app lifetime

Unlike a simple singleton app services must only live for the duration of the app and must support multiple parallel instances if built with the "multi_app" feature. You can use private app_local! static variables as backing storage to fulfill this requirement.

A common pattern in the zng services is to name the app locals with a _SV suffix.

Services do not expose the app local locking, all state output is cloned the state is only locked for the duration of the service method call.

§App services don’t change public state mid update

All widgets using the service during the same update see the same state. State change requests are scheduled for the next update, just like variable updates or event notifications. Services also request an UPDATES.update after scheduling to wake-up the app in case the service request was made from a task thread.

This is even true for the INSTANT service, although this can be configured for this service using APP.pause_time_for_update.

§Examples

Fulfilling service requests is where the AppExtension comes in, it is possible to declare a simple standalone service using only variables, Event::on_event and UPDATES.run_hn_once, but an app extension is more efficient and more easy to implement.

If the service request can fail or be delayed it is common for the request method to return a ResponseVar<R> that is updated once the request is finished. You can also make the method async, but a response var is superior because it can be plugged directly into any UI property, and it can still be awaited using the variable async methods.

If the service request cannot fail and it is guaranteed to affect an observable change in the service state in the next update a response var is not needed.

The example below demonstrates an app extension implementation that provides a service.

use zng::{app::AppExtension, prelude_wgt::*};

/// Foo service.
pub struct FOO;

impl FOO {
    /// Foo read-write var.
    pub fn config(&self) -> Var<bool> {
        FOO_SV.read().config.clone()
    }

    /// Foo request.
    pub fn request(&self, request: char) -> ResponseVar<char> {
        UPDATES.update(None);

        let mut foo = FOO_SV.write();
        let (responder, response) = response_var();
        foo.requests.push((request, responder));
        response
    }
}

struct FooService {
    config: Var<bool>,
    requests: Vec<(char, ResponderVar<char>)>,
}

app_local! {
    static FOO_SV: FooService = FooService {
        config: var(false),
        requests: vec![],
    };
}

/// Foo app extension.
///
/// # Services
///
/// Services provided by this extension.
///
/// * [`FOO`]
#[derive(Default)]
#[non_exhaustive]
pub struct FooManager {}

impl AppExtension for FooManager {
    fn update(&mut self) {
        let mut foo = FOO_SV.write();

        if let Some(cfg) = foo.config.get_new() {
            println!("foo cfg={cfg}");
        }

        for (request, responder) in foo.requests.drain(..) {
            println!("foo request {request:?}");
            responder.respond(request);
        }
    }
}

Note that in the example requests are processed in the AppExtension::update update that is called after all widgets have had a chance to make requests. Requests can also be made from parallel task threads so the service also requests an UPDATES.update just in case there is no update running. If you expect to receive many requests from parallel tasks you can also process requests in the AppExtension::update instead, but there is probably little practical difference.

§Init & Main Loop

A headed app initializes in this sequence:

AppExtension::register is called.
Spawn view-process.
AppExtension::init is called.
Schedule the app run future to run in the first preview update.
Does updates loop.
Does update events loop.
Does main loop.

§Main Loop

The main loop coordinates view-process events, timers, app events and updates. There is no scheduler, update and event requests are captured and coalesced to various buffers that are drained in known sequential order. App extensions update one at a time in the order they are registered. Windows and widgets update in parallel by default, this is controlled by WINDOWS.parallel and parallel.

Sleep if there are not pending events or updates.
- If the view-process is busy blocks until it sends a message, this is a mechanism to stop the app-process from overwhelming the view-process.
- Block until a message is received, from the view-process or from other app threads.
- If there are TIMERS or VARS animations the message block has a deadline to the nearest timer or animation frame.
  - Animations have a fixed frame-rate defined in VARS.frame_duration, it is 60 frames-per-second by default.
Calls elapsed timer handlers.
Calls elapsed animation handlers.
- These handlers mostly just request var updates that are applied in the updates loop.
Does a view events loop.
Does an updates loop.
Does an update events loop.
If the view-process is not busy does a layout loop and render.
If exit was requested and not cancelled breaks the loop.
- Exit is requested automatically when the last open window closes, this is controlled by WINDOWS.exit_on_last_close.
- Exit can also be requested using APP.exit.

§View Events Loop

All pending events received from the view-process are coalesced and notify sequentially.

For each event in the received order (FIFO) that converts to a RAW_*_EVENT.
1. Calls AppExtension::event_preview.
2. Calls Event::on_pre_event handlers.
3. Calls AppExtension::event_ui.
  - Raw events don’t target any widget, but widgets can subscribe, subscribers receive the event in parallel by default.
4. Calls AppExtension::event.
5. Calls Event::on_event handlers.
6. Does an updates loop.
Frame rendered raw event.
- Same notification sequence as other view-events, just delayed.

§Updates Loop

The updates loop rebuilds info trees if needed , applies pending variable updates and hooks and collects event updates requested by the app.

Takes info rebuild request flag.
- Calls AppExtension::info if needed.
- Windows and widgets that requested info (re)build are called.
- Info rebuild happens in parallel by default.
Takes events and updates requests.
1. Event hooks are called for new event requests.
  - Full event notification is delayed to after the updates loop.
2. var updates loop
3. Calls AppExtension::update_preview if any update was requested.
4. Calls UPDATES.on_pre_update handlers if needed.
5. Calls AppExtension::update_ui if any update was requested.
  - Windows and widgets that requested update receive it here.
  - All the pending updates are processed in one pass, all targeted widgets are visited once, in parallel by default.
6. Calls AppExtension::update if any update was requested.
7. Calls UPDATES.on_update handlers if needed.
The loop repeats immediately if any info rebuild or update was requested by update callbacks.
- The loops breaks if it repeats over 1000 times.
- An error is logged with a trace of the most frequent sources of update requests.

§Var Updates Loop

The variable updates loop applies pending modifications, calls hooks to update variable and bindings.

Pending variable modifications are applied.
Var hooks are called.
- The mapping and binding mechanism is implemented using hooks.
The loop repeats until hooks have stopped modifying variables.
- The loop breaks if it repeats over 1000 times.
- An error is logged if this happens.

§Update Events Loop

The update events loop notifies each event raised by the app code during previous updates.

For each event in the request order (FIFO).
1. Calls AppExtension::event_preview.
2. Calls Event::on_pre_event handlers.
3. Calls AppExtension::event_ui.
  - Windows and widgets targeted by the event update receive it here.
  - If the event targets multiple widgets they receive it in parallel by default.
4. Calls AppExtension::event.
5. Calls Event::on_event handlers.
6. Does an updates loop.

§Layout Loop and Render

Layout and render requests are coalesced, multiple layout requests for the same widget update it once, multiple render requests become one frame, and if both render and render_update are requested for a window it will just fully render.

Take layout and render requests.
Layout loop.
1. Calls AppExtension::layout.
  - Windows and widgets that requested layout update in parallel by default.
2. Does an updates loop.
3. Does update events loop.
4. Take layout and render requests, the loop repeats immediately if layout was requested again.
  - The loop breaks if it repeats over 1000 times.
  - An error is logged with a trace the most frequent sources of update requests.
If render was requested, calls AppExtension::render.
- Windows and widgets that requested render (or render_update) are rendered in parallel by default.
- The render pass updates widget transforms and hit-test, generates a display list and sends it to the view-process.

§Full API

This module provides most of the app API needed to make and extend apps, some more advanced or experimental API may be available at the zng_app, zng_app_context and zng_ext_single_instance base crates.

Modules§

crash_handler: App-process crash handler.
memory_profiler: Heap memory usage profiling.
raw_device_events: Input device hardware ID and events.
trace_recorder: Trace recording and data model.

Macros§

app_local: Declares new app local variable.
context_local: Declares new app and context local variable.

Structs§

AppExtended: Application builder.
AppExtensionInfo: Info about an app-extension.
AppId: Identifies an app instance.
AppInstanceArgs: Arguments for APP_INSTANCE_EVENT.
AppLocal: An app local storage.
AppScope: Represents an app lifetime, ends the app on drop.
AppStartArgs: Arguments for on_app_start handlers.
ContextLocal: Represents an AppLocal<T> value that can be temporarily overridden in a context.
ContextValueSet: Identifies a selection of LocalContext values.
DInstant: Duration elapsed since an epoch.
Deadline: Represents a timeout instant.
ExitRequestedArgs: Arguments for EXIT_REQUESTED_EVENT.
HeadlessApp: A headless app controller.
INSTANT: Instant service.
LocalContext: Tracks the current execution context.
LowMemoryArgs: Arguments for LOW_MEMORY_EVENT.
MappedRwLockReadGuardOwned: Represents a read guard for an Arc<RwLock<T>> that owns a reference to it, mapped from another read guard.
MappedRwLockWriteGuardOwned: Represents a write guard for an Arc<RwLock<T>> that owns a reference to it, mapped from another read guard.
ReadOnlyRwLock: Read-only wrapper on an Arc<RwLock<T>> contextual value.
RunOnDrop: Helper, runs a cleanup action once on drop.
RwLockReadGuardOwned: Represents a read guard for an Arc<RwLock<T>> that owns a reference to it.
RwLockWriteGuardOwned: Represents a read guard for an Arc<RwLock<T>> that owns a reference to it.

Enums§

AppControlFlow: Desired next step of app main loop.
CaptureFilter: Defines a LocalContext::capture_filtered filter.
InstantMode: Defines how the INSTANT.now value updates in the app.

Statics§

APP_INSTANCE_EVENT: App instance init event, with the arguments.
EXIT_CMD: Represents the app process exit request.
EXIT_REQUESTED_EVENT: Cancellable event raised when app process exit is requested.
LOW_MEMORY_EVENT: System low memory warning, some platforms may kill the app if it does not release memory.
NEW_CMD: Represents the new action.
OPEN_CMD: Represents the open action.
SAVE_AS_CMD: Represents the save-as action.
SAVE_CMD: Represents the save action.

Traits§

AppEventObserver: Observer for HeadlessApp::update_observed.
AppExtension: An app extension.

Functions§

can_new: P Defines if on_new and on_pre_new command handles are enabled in the context.
can_open: P Defines if on_open and on_pre_open command handles are enabled in the context.
can_save: P Defines if on_save and on_pre_save command handles are enabled in the context.
can_save_as: P Defines if on_save_as and on_pre_save_as command handles are enabled in the context.
on_app_start: Register a handler to run when an APP starts running in the process.
on_new: P On new command.
on_open: P On open command.
on_pre_new: P Preview on_new command.
on_pre_open: P Preview on_open command.
on_pre_save: P Preview on_save command.
on_pre_save_as: P Preview on_save_as command.
on_save: P On save command.
on_save_as: P On save-as command.
print_tracing: Enables tracing events printing if a subscriber is not already set.
print_tracing_filter: Filter used by print_tracing, removes some log noise from dependencies.
spawn_deadlock_detection: When compiled with "deadlock_detection" spawns a thread that monitors for parking_lot deadlocks.
test_log: Modifies the print_tracing subscriber to panic for error logs in the current app.

Module app

Module app Copy item path

§Runtime

§View-Process

§Same Process

§Headless

§App Extension

§Services

§App services are an unit struct named like a static

§App services lifetime is the current app lifetime

§App services don’t change public state mid update

§Examples

§Init & Main Loop

§Main Loop

§View Events Loop

§Updates Loop

§Var Updates Loop

§Update Events Loop

§Layout Loop and Render

§Full API

Modules§

Macros§

Structs§

Enums§

Statics§

Traits§

Functions§

Module app