//! Timer and thread management for asynchronous operations.

//!

//! This module provides:

//! - `TimerId` / `ThreadId`: Unique identifiers for timers and background threads

//! - `Instant` / `Duration`: Cross-platform time types (works on no_std with tick counters)

//! - `ThreadReceiver`: Channel for receiving messages from the main thread

//! - Callback types for thread communication and system time queries

#[cfg(not(feature = "std"))]

use alloc::string::{String, ToString};

use alloc::{

    boxed::Box,

    collections::btree_map::BTreeMap,

    sync::{Arc, Weak},

    vec::Vec,

};

use core::{

    ffi::c_void,

    fmt,

    mem::ManuallyDrop,

    sync::atomic::{AtomicUsize, Ordering},

};

#[cfg(feature = "std")]

use std::sync::mpsc::{Receiver, Sender};

#[cfg(feature = "std")]

use std::sync::Mutex;

#[cfg(feature = "std")]

use std::thread::{self, JoinHandle};

#[cfg(feature = "std")]

use std::time::Duration as StdDuration;

#[cfg(feature = "std")]

use std::time::Instant as StdInstant;

use azul_css::{props::property::CssProperty, AzString};

use rust_fontconfig::FcFontCache;

use crate::{

    callbacks::{FocusTarget, TimerCallbackReturn, Update},

    dom::{DomId, DomNodeId, OptionDomNodeId},

    geom::{LogicalPosition, OptionLogicalPosition},

    gl::OptionGlContextPtr,

    hit_test::ScrollPosition,

    id::NodeId,

    refany::{OptionRefAny, RefAny},

    resources::{ImageCache, ImageMask, ImageRef},

    styled_dom::NodeHierarchyItemId,

    window::RawWindowHandle,

    FastBTreeSet, OrderedMap,

};

/// Should a timer terminate or not - used to remove active timers

#[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]

#[repr(C)]

pub enum TerminateTimer {

    /// Remove the timer from the list of active timers

    Terminate,

    /// Do nothing and let the timers continue to run

    Continue,

}

// ============================================================================

// Reserved System Timer IDs (0x0000 - 0x00FF)

// ============================================================================

// User timers start at 0x0100 to avoid conflicts with system timers.

// These constants define well-known timer IDs for internal framework use.

/// Timer ID for cursor blinking in contenteditable elements (~530ms interval)

pub const CURSOR_BLINK_TIMER_ID: TimerId = TimerId { id: 0x0001 };

/// Timer ID for scroll momentum/inertia animation

pub const SCROLL_MOMENTUM_TIMER_ID: TimerId = TimerId { id: 0x0002 };

/// Timer ID for auto-scroll during drag operations near edges

pub const DRAG_AUTOSCROLL_TIMER_ID: TimerId = TimerId { id: 0x0003 };

/// Timer ID for tooltip show delay.

///

/// Started by the platform event loop when the hover target changes to a node

/// that advertises a tooltip source (`aria-label` / `alt` / `title`); fires

/// once after `SystemStyle::input_metrics.hover_time_ms` (`SPI_GETMOUSEHOVERTIME`

/// on Windows, default 400ms) and emits a `ShowTooltip` `CallbackChange`. The

/// timer is torn down on hover loss, which also emits `HideTooltip`.

///

/// Double-click detection used to live on a neighbouring reserved ID but is

/// now handled entirely by `GestureManager::detect_double_click`, so no

/// equivalent `DOUBLE_CLICK_TIMER_ID` exists.

pub const TOOLTIP_DELAY_TIMER_ID: TimerId = TimerId { id: 0x0004 };

/// Timer ID for the single-threaded capability pump (MWA-A1).

///

/// Armed by `sync_capability_pump_timer` whenever a capability source needs

/// polling or draining while the app is otherwise idle (gamepad listeners,

/// sensor listeners, an active geolocation subscription). Each tick wakes the

/// blocked platform loop; `invoke_expired_timers` then runs an event pass,

/// whose top-of-pass pump drains the async capability channels. There is NO

/// pump thread by design — a recurring shell timer is the only wake

/// mechanism, so the identical code path works on WASM (no threads).

pub const CAPABILITY_PUMP_TIMER_ID: TimerId = TimerId { id: 0x0005 };

/// Timer ID for the one-shot long-press wake-up (MWA-B12).

///

/// Armed on every `MouseDown` for the long-press threshold: a motionless

/// press generates no further events, so no pass would ever evaluate

/// `detect_long_press` — this timer wakes the loop exactly once at the

/// threshold, `invoke_expired_timers` runs an event pass, and the

/// detection fires (or doesn't — moved/released holds are no-ops).

pub const LONG_PRESS_TIMER_ID: TimerId = TimerId { id: 0x0006 };

/// Reserved timer ID for the caret / selection tween driver (~16ms).

///

/// Armed by the shared event dispatcher whenever a text tween is in flight; the

/// callback terminates itself the tick after the tween state goes idle.

pub const CARET_TWEEN_TIMER_ID: TimerId = TimerId { id: 0x0007 };

/// First available ID for user-defined timers

pub const USER_TIMER_ID_START: usize = 0x0100;

// User timers start at 0x0100 to avoid conflicts with reserved system timer IDs

static MAX_TIMER_ID: AtomicUsize = AtomicUsize::new(USER_TIMER_ID_START);

/// ID for uniquely identifying a timer

#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]

#[repr(C)]

pub struct TimerId {

    pub id: usize,

}

impl TimerId {

    /// Generates a new, unique `TimerId`.

    #[must_use]

}

impl_option!(

    TimerId,

    OptionTimerId,

    [Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash]

);

impl_vec!(TimerId, TimerIdVec, TimerIdVecDestructor, TimerIdVecDestructorType, TimerIdVecSlice, OptionTimerId);

impl_vec_debug!(TimerId, TimerIdVec);

impl_vec_clone!(TimerId, TimerIdVec, TimerIdVecDestructor);

impl_vec_partialeq!(TimerId, TimerIdVec);

impl_vec_partialord!(TimerId, TimerIdVec);

// Thread IDs 0-4 are reserved for internal framework use.

// User threads start at RESERVED_THREAD_ID_COUNT.

const RESERVED_THREAD_ID_COUNT: usize = 5;

static MAX_THREAD_ID: AtomicUsize = AtomicUsize::new(RESERVED_THREAD_ID_COUNT);

/// ID for uniquely identifying a background thread

#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]

#[repr(C)]

pub struct ThreadId {

    id: usize,

}

impl_option!(

    ThreadId,

    OptionThreadId,

    [Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash]

);

impl_vec!(ThreadId, ThreadIdVec, ThreadIdVecDestructor, ThreadIdVecDestructorType, ThreadIdVecSlice, OptionThreadId);

impl_vec_debug!(ThreadId, ThreadIdVec);

impl_vec_clone!(ThreadId, ThreadIdVec, ThreadIdVecDestructor);

impl_vec_partialeq!(ThreadId, ThreadIdVec);

impl_vec_partialord!(ThreadId, ThreadIdVec);

impl ThreadId {

    /// Generates a new, unique `ThreadId`.

    #[must_use]

}

/// A point in time, either from the system clock or a tick counter.

///

/// Use `Instant::System` on platforms with std, `Instant::Tick` on `embedded/no_std`.

#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]

#[repr(C, u8)]

pub enum Instant {

    /// System time from `std::time::Instant` (requires "std" feature)

    System(InstantPtr),

    /// Tick-based time for embedded systems without a real-time clock

    Tick(SystemTick),

}

#[cfg(feature = "std")]

impl From<StdInstant> for Instant {

}

#[cfg(feature = "std")]

std::thread_local! {

    /// Injectable test-clock offset, in milliseconds, added to every

    /// `Instant::now()` **on this thread**.

    ///

    /// Driven by the E2E `tick_ms` op. Everything time-driven in the engine —

    /// scroll momentum, scrollbar fade, cursor blink, animations, timers —

    /// reads the clock through `Instant::now()` / `get_system_time_libstd()`,

    /// so advancing this offset moves all of them forward by exactly N ms

    /// WITHOUT sleeping. That is what makes "drive the animation to completion

    /// and assert it converges" deterministic instead of a `wait { ms }` race.

    ///

    /// Zero in production; only the debug-server `tick_ms` op ever writes it.

    ///

    /// # Why this is a thread-local and not a `static AtomicU64`

    ///

    /// It used to be process-global, which made the clock a shared mutable

    /// resource: every scenario that ticked had to run SERIALLY, or scenario

    /// A's `tick_ms` would shift scenario B's animations mid-frame. Since the

    /// corpus is dominated by idle/animation scenarios, that serialised

    /// essentially the whole suite.

    ///

    /// The read path is [`GetSystemTimeCallbackType`] — a bare

    /// `extern "C" fn() -> Instant` in the public C API — plus ~140 direct

    /// `Instant::now()` calls. Neither can carry a window, an app or a clock

    /// handle without either breaking the C ABI for every language binding or

    /// threading a time source through every call site including `no_std`

    /// ones. A thread-local is the narrowest scope a context-free C callback

    /// can read: it turns "the whole process" into "the thread that owns this

    /// scenario", which is exactly the ownership boundary the parallel E2E

    /// runner already establishes (one scenario runs start-to-finish on one

    /// worker thread). [`reset_test_clock`] makes that boundary explicit.

    static TEST_CLOCK_OFFSET_MS: core::cell::Cell<u64> = const { core::cell::Cell::new(0) };

}

/// Advance the injectable test clock by `ms` (E2E `tick_ms`), returning the new

/// offset. Affects only the CURRENT thread — see [`TEST_CLOCK_OFFSET_MS`].

#[cfg(feature = "std")]

#[must_use]

/// The current test-clock offset in ms (0 unless `tick_ms` was used on this

/// thread).

#[cfg(feature = "std")]

#[must_use]

#[cfg(feature = "std")]

#[cfg(all(feature = "std", not(target_arch = "wasm32")))]

std::thread_local! {

    /// When set, this thread's clock is FROZEN at this instant: `Instant::now()`

    /// answers `base + TEST_CLOCK_OFFSET_MS` and real time does not flow into it

    /// at all. See [`freeze_test_clock`].

    static TEST_CLOCK_BASE: core::cell::Cell<Option<StdInstant>> =

        const { core::cell::Cell::new(None) };

}

/// Freeze this thread's clock, so engine time advances ONLY when a scenario says

/// it does (`tick_ms` / `wait`) and never because wall time passed.

///

/// Offsetting alone is not enough. `Instant::now()` was

/// `StdInstant::now() + offset`, so the REAL component still flowed and every

/// time-driven behaviour rode on however long the machine happened to take:

/// elapsed = (exact virtual) + (whatever this build, under this load, spent

/// computing). The E2E suite runs 8 scenarios per core, so that second term is

/// both large and variable, and an assertion on a blinking caret's phase would

/// flip between runs on a loaded runner while passing every time in isolation.

///

/// Frozen, engine time becomes a pure function of the ops a scenario executed —

/// identical on a debug build, a release build and a saturated CI box. That is

/// also what makes an off-by-one in animation timing *observable*: advance

/// exactly one interval and the frame either flipped or it did not, with no

/// jitter to hide behind.

///

/// This deliberately does NOT touch [`Instant::Tick`]. Interval constants are

/// built as `Duration::System` (e.g. the cursor blink in `text_edit`), and

/// `Duration::greater_than` compares only matching variants — handing the engine

/// `Tick` elapsed values against `System` intervals would mismatch and silently

/// answer "not yet" forever. Freezing keeps every existing comparison intact.

///

/// Idempotent: re-freezing an already-frozen clock keeps the original base, so

/// the offset stays the single source of elapsed time.

#[cfg(all(feature = "std", not(target_arch = "wasm32")))]

/// Whether this thread's clock is frozen (see [`freeze_test_clock`]).

#[cfg(all(feature = "std", not(target_arch = "wasm32")))]

#[must_use]

/// Put this thread's test clock back on real time.

///

/// Worker threads are REUSED across scenarios, so without this the next

/// scenario scheduled onto this thread would inherit the previous one's

/// accumulated offset — the same cross-contamination the process-global

/// offset had, just at thread granularity. The E2E runner calls this at the

/// start of every scenario. Clears the freeze as well, so a scenario cannot

/// leave the next one's clock stopped.

#[cfg(all(feature = "std", not(target_arch = "wasm32")))]

/// Monotonic frame counter, and the ONLY clock a wasm build has.

///

/// `std::time::Instant::now()` PANICS on wasm32-unknown-unknown, and

/// `#[cfg(feature = "std")]` does not exclude wasm here: azul-core is built with

/// `default = ["std"]` for the web target, so every `std` path is compiled in.

///

/// Answering `Tick(0)` forever would stop the panic and freeze every animation

/// instead — a silent stall, which is worse than a loud crash. So the web build

/// gets a real monotonic source: the browser drives redraw, each produced DOM

/// patch is one frame, and one frame is exactly what a `t` (tick) duration

/// counts. `AzStartup_buildPatch` calls [`advance_system_tick`] once per patch.

#[cfg(feature = "std")]

static SYSTEM_TICK: core::sync::atomic::AtomicU64 = core::sync::atomic::AtomicU64::new(0);

/// Advance the frame counter by one. Called once per produced frame by backends

/// that have no wall clock. Cheap enough to call unconditionally.

#[cfg(feature = "std")]

/// The current frame counter.

#[cfg(feature = "std")]

#[must_use]

/// `std::time::Instant::now()` shifted by the injectable test-clock offset, or —

/// when the clock is frozen — built from the frozen base so real time cannot

/// leak in.

///

/// NOT COMPILED on wasm32, where `std::time::Instant::now()` panics.

///

/// `web_lift` is deliberately NOT included here. That backend compiles natively

/// and is lifted to wasm afterwards, so `target_arch` reads `x86_64` — but the

/// lift walks the LLVM graph and auto-inserts calls out to JS for things like

/// time, so it supplies its own clock and does not want this arm disabled.

#[cfg(all(feature = "std", not(target_arch = "wasm32")))]

    } else {

    }

impl Instant {

    /// Returns the current system time.

    ///

    /// On systems with std, this uses `std::time::Instant::now()`.

    /// On `no_std` systems, this returns a zero tick.

    #[cfg(all(feature = "std", not(target_arch = "wasm32")))]

    /// Returns the current time on wasm32, which has no clock to read.

    ///

    /// `std::time::Instant::now()` panics on wasm32-unknown-unknown, and

    /// `#[cfg(feature = "std")]` does not exclude wasm here — azul-core is built

    /// with `default = ["std"]` for the web target, so the std path is compiled

    /// in and would trap on the first frame.

    ///

    /// This deliberately does NOT answer a constant `Tick(0)`. That stops the

    /// panic and freezes every animation instead, which is a silent stall — the

    /// worse failure of the two. The browser drives redraw and each produced DOM

    /// patch is one frame, so the frame counter IS the clock, and a frame is

    /// exactly what a `t` (tick) duration counts. Elapsed values come out as

    /// `Tick` and convert against `System` intervals through

    /// `Duration::as_nanos`, so `60t` compares equal to one second.

    #[cfg(all(feature = "std", target_arch = "wasm32"))]

    #[must_use] pub fn now() -> Self {

        Instant::Tick(SystemTick::new(system_tick_now()))

    }

    /// Returns the current system time (no_std fallback).

    #[cfg(not(feature = "std"))]

    pub fn now() -> Self {

        Instant::Tick(SystemTick::new(0))

    }

    /// Returns a number from 0.0 to 1.0 indicating the current

    /// linear interpolation value between (start, end)

        use core::mem;

        // Zero-length interval: `duration_current / duration_total` would be

        // `0/0 = NaN`. Treat a collapsed interval as fully elapsed (1.0) rather

        // than propagating NaN into animation progress.

    /// Adds a duration to the instant.

    ///

    /// The duration's UNIT need not match the instant's: a `Tick` duration added

    /// to a `System` instant is converted at [`TICKS_PER_SECOND`], and a `System`

    /// duration added to a `Tick` instant is converted to whole ticks.

    ///

    /// # Why the mismatch is converted rather than dropped

    ///

    /// This used to return `self` unchanged for a unit mismatch, which turned a

    /// `Duration::Tick` interval on a wall-clock timer into a schedule point of

    /// `last_run + 0` — `Timer::instant_of_next_run` is literally

    /// `last_run + delay + interval`, so the timer reported itself permanently

    /// overdue and `LayoutWindow::time_until_next_timer_ms` answered `Some(0)`

    /// for it, i.e. "block for zero milliseconds" to any loop that consults it.

    ///

    /// `System + System` still overflow-panics on an absurd duration (that is

    /// `StdInstant`'s own behaviour, characterised in the tests); the tick arms

    /// saturate.

                    #[cfg(feature = "std")]

                    {

                    }

                    #[cfg(not(feature = "std"))]

                    {

                        // A `System` instant cannot be constructed on no_std, so

                        // this arm is unreachable in practice; return self rather

                        // than aborting.

                        let _ = (i, d);

                        self.clone()

                    }

                }

                // System instant + Tick duration: convert the frame count to wall

                // time. Routed through the same `System + System` arm so the

                // overflow behaviour is identical for both units.

                (Self::System(_), Duration::Tick(_)) => {

                }

                // Tick instant + System duration: convert to WHOLE ticks. A

                // sub-frame duration therefore advances nothing, which is the

                // truthful answer on a clock whose resolution is one frame.

    /// Converts to `std::time::Instant` (panics if Tick variant).

    #[cfg(feature = "std")]

        }

    /// Calculates the duration since an earlier point in time.

    ///

    /// Saturates to a zero duration in the degenerate cases (earlier is actually

    /// *later* than `self`, or the two instants are of mismatched kinds) instead

    /// of panicking — this runs on the hot event-loop path and must not crash.

                #[cfg(feature = "std")]

                {

                    // `saturating_duration_since` yields 0 if `prev` is later

                    // than `now` (monotonic-clock skew / reordered instants).

                }

                #[cfg(not(feature = "std"))]

                {

                    // Unreachable on no_std (no System instants); saturate to 0.

                    let _ = (prev, now);

                    Duration::Tick(SystemTickDiff { tick_diff: 0 })

                }

            }

            (

            // Mismatched kinds: no meaningful span -> saturate to 0.

        }

}

/// Tick-based timestamp for systems without a real-time clock.

///

/// Used on embedded systems where time is measured in frame ticks or cycles.

#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]

#[repr(C)]

pub struct SystemTick {

    pub tick_counter: u64,

}

impl SystemTick {

    /// Creates a new tick timestamp from a counter value.

}

/// FFI-safe wrapper around `std::time::Instant` with custom clone/drop callbacks.

///

/// Allows crossing FFI boundaries while maintaining proper memory management.

#[repr(C)]

pub struct InstantPtr {

    /// `ManuallyDrop` so the owned `Box` is freed ONLY when `run_destructor` is

    /// still set (see `Drop`). The codegen FFI wrappers (`AzTimerCallbackInfo`

    /// etc.) embed this by value AND have their own `Drop` that `drop_in_place`s

    /// the real type first; Rust's drop glue would then drop this `ptr` field a

    /// SECOND time on the same bytes. Gating the `Box` free on `run_destructor`

    /// (cleared by the first drop) makes that second drop a safe no-op. Layout is

    /// unchanged: `ManuallyDrop<Box<T>>` is one pointer, like the old `Box<T>`.

    #[cfg(feature = "std")]

    pub ptr: ManuallyDrop<Box<StdInstant>>,

    #[cfg(not(feature = "std"))]

    pub ptr: *const c_void,

    pub clone_fn: InstantPtrCloneCallback,

    pub destructor: InstantPtrDestructorCallback,

    pub run_destructor: bool,

}

pub type InstantPtrCloneCallbackType = extern "C" fn(*const InstantPtr) -> InstantPtr;

#[repr(C)]

pub struct InstantPtrCloneCallback {

    pub cb: InstantPtrCloneCallbackType,

}

impl_callback_simple!(InstantPtrCloneCallback);

pub type InstantPtrDestructorCallbackType = extern "C" fn(*mut InstantPtr);

#[repr(C)]

pub struct InstantPtrDestructorCallback {

    pub cb: InstantPtrDestructorCallbackType,

}

impl_callback_simple!(InstantPtrDestructorCallback);

// ----  LIBSTD implementation for InstantPtr BEGIN

#[cfg(feature = "std")]

impl fmt::Debug for InstantPtr {

}

#[cfg(not(feature = "std"))]

impl core::fmt::Debug for InstantPtr {

    fn fmt(&self, f: &mut ::core::fmt::Formatter) -> ::core::fmt::Result {

        write!(f, "{:?}", self.ptr as usize)

    }

}

#[cfg(feature = "std")]

impl core::hash::Hash for InstantPtr {

}

#[cfg(not(feature = "std"))]

impl core::hash::Hash for InstantPtr {

    fn hash<H: core::hash::Hasher>(&self, state: &mut H) {

        (self.ptr as usize).hash(state);

    }

}

#[cfg(feature = "std")]

impl PartialEq for InstantPtr {

}

#[cfg(not(feature = "std"))]

impl PartialEq for InstantPtr {

    fn eq(&self, other: &InstantPtr) -> bool {

        (self.ptr as usize).eq(&(other.ptr as usize))

    }

}

impl Eq for InstantPtr {}

#[cfg(feature = "std")]

impl PartialOrd for InstantPtr {

}

#[cfg(not(feature = "std"))]

impl PartialOrd for InstantPtr {

    fn partial_cmp(&self, other: &Self) -> Option<::core::cmp::Ordering> {

        Some((self.ptr as usize).cmp(&(other.ptr as usize)))

    }

}

#[cfg(feature = "std")]

impl Ord for InstantPtr {

}

#[cfg(not(feature = "std"))]

impl Ord for InstantPtr {

    fn cmp(&self, other: &Self) -> ::core::cmp::Ordering {

        (self.ptr as usize).cmp(&(other.ptr as usize))

    }

}

#[cfg(feature = "std")]

impl InstantPtr {

}

impl Clone for InstantPtr {

}

#[cfg(feature = "std")]

#[cfg(feature = "std")]

impl From<StdInstant> for InstantPtr {

}

#[cfg(feature = "std")]

impl From<InstantPtr> for StdInstant {

}

impl Drop for InstantPtr {

            // Free the owned Box exactly once, here under the run_destructor guard.

            // A second drop on the same bytes (the codegen wrapper's field-drop after

            // its own `_delete` already ran the real drop) sees run_destructor=false

            // and skips this -> no double-free. (non-std `ptr` is a raw POD pointer

            // freed by the destructor callback above, so nothing to drop here.)

            // SAFETY: `run_destructor` is set false above, so this arm runs at

            // most once per InstantPtr value; the `Box` inside was never moved

            // out, so it is live and owned here and safe to drop exactly once.

            #[cfg(feature = "std")]

}

#[cfg(feature = "std")]

// ----  LIBSTD implementation for InstantPtr END

/// A span of time, either from the system clock or as tick difference.

///

/// Mirrors `Instant` variants - System durations work with System instants,

/// Tick durations work with Tick instants.

#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]

#[repr(C, u8)]

pub enum Duration {

    /// System duration from `std::time::Duration` (requires "std" feature)

    System(SystemTimeDiff),

    /// Tick-based duration for embedded systems

    Tick(SystemTickDiff),

}

impl fmt::Display for Duration {

            #[cfg(feature = "std")]

            }

            #[cfg(not(feature = "std"))]

            Duration::System(s) => write!(f, "({}s, {}ns)", s.secs, s.nanos),

        }

}

#[cfg(feature = "std")]

impl From<StdDuration> for Duration {

}

/// Nominal engine tick (frame) rate — the single exchange rate between

/// [`Duration::Tick`] (frames) and [`Duration::System`] (wall time).

///

/// Re-exported from `azul-css` so the CSS `t` unit and the engine's `Duration`

/// arithmetic cannot drift apart. See [`azul_css::props::basic::time::TICKS_PER_SECOND`].

pub use azul_css::props::basic::time::TICKS_PER_SECOND;

impl Duration {

    /// This duration on ONE canonical scale, in nanoseconds — the common ground

    /// on which a `Tick` span and a `System` span can be compared.

    ///

    /// `u128` because a `System` duration holds up to `u64::MAX` *seconds*

    /// (~1.8e28 ns), which does not fit `u64`. The tick conversion multiplies

    /// before it divides so whole seconds stay exact: `60t` is `1_000_000_000`ns,

    /// not `60 * 16_666_666 = 999_999_960`ns.

    ///

    /// Note this also normalises a DENORMALISED `SystemTimeDiff` (`nanos` past

    /// `1e9`) the same way `std::time::Duration::new` would — except it cannot

    /// panic on overflow while doing it.

    // `as u128` rather than `u128::from`: this is a `const fn` and `From` is not

    // const. Every one of these widenings is lossless.

    #[allow(clippy::cast_lossless)]

    #[must_use]

        }

    /// A wall-clock duration of `ms` whole milliseconds.

    #[must_use]

    /// A duration of `ticks` engine frames — the clockless unit, and what the

    /// CSS `t` unit becomes.

    #[must_use]

    /// This duration in whole ticks (frames), truncating toward zero.

    ///

    /// A sub-frame span is **zero** ticks, not one: "how many whole frames fit",

    /// never "round up so that something happens".

    // `as` casts: `const fn`, so `From`/`TryFrom` are unavailable. The widenings

    // are lossless and the u128 -> u64 narrowing is range-checked immediately

    // above it.

    #[allow(clippy::cast_lossless, clippy::cast_possible_truncation)]

    #[must_use]

            Self::System(_) => {

                } else {

                }

            }

        }

    /// This duration in whole milliseconds, truncating toward zero and

    /// saturating at `u64::MAX` rather than wrapping.

    // `as` casts: `const fn`, so `From`/`TryFrom` are unavailable. The u128 ->

    // u64 narrowing is range-checked immediately above it.

    #[allow(clippy::cast_lossless, clippy::cast_possible_truncation)]

    #[must_use]

        } else {

        }

    /// Returns the maximum possible duration.

        #[cfg(feature = "std")]

        {

        }

        #[cfg(not(feature = "std"))]

        {

            Duration::Tick(SystemTickDiff {

                tick_diff: u64::MAX,

            })

        }

    /// Divides this duration by another, returning the ratio as f32.

    ///

    /// Same-unit division goes through the unit's own `div` so its exact

    /// floating-point result is unchanged. Cross-unit division falls back to the

    /// canonical nanosecond scale rather than returning `0.0` — a `0.0` ratio

    /// here means "animation is at 0% progress", which is a frozen animation, not

    /// an error anyone would notice.

    // the f64 ratio is intentionally narrowed to the f32 return type; the value

    // is a duration ratio, far inside f32's range.

    #[allow(clippy::cast_possible_truncation, clippy::cast_precision_loss)]

        use self::Duration::{System, Tick};

            // u128 -> f64 loses precision only past 2^53 ns (~104 days), and the

            // result is a ratio that is then narrowed to f32 anyway.

        }

    /// Returns the smaller of two durations.

        } else {

        }

    /// Returns true if self > other.

    ///

    /// Compares on the canonical nanosecond scale ([`Self::as_nanos`]), so a

    /// `Tick` span and a `System` span compare TRUTHFULLY against each other.

    ///

    /// # Why this is not "mismatched kinds saturate to false"

    ///

    /// It used to be. That made a unit mismatch invisible and permanent instead

    /// of loud: the engine's interval constants are `Duration::System` (the

    /// cursor blink, the scrollbar fade, the tooltip delay), so the moment a

    /// clock produced `Tick` elapsed values every one of those comparisons

    /// answered "not yet" — forever. Nothing panicked, nothing logged, the UI

    /// simply stopped animating. That is precisely the failure a clockless unit

    /// is supposed to make *catchable*, so the comparison has to be total.

    ///

    /// Three behaviours changed, all in the safe direction:

    ///

    /// 1. Cross-unit comparisons now answer, instead of always `false`.

    /// 2. On `no_std` the `System`/`System` arm used to be hardcoded `false`

    ///    (there was no `StdDuration` to defer to); it now compares properly.

    /// 3. A denormalised `SystemTimeDiff` whose `secs + nanos/1e9` overflows

    ///    `u64` used to panic inside `StdDuration::new`; `u128` nanoseconds

    ///    cannot overflow.

    /// Returns true if self < other.

    ///

    /// Canonical-scale comparison; see [`Self::greater_than`] for why this is

    /// unit-aware rather than saturating to `false` on a unit mismatch.

}

/// Represents a difference in ticks for systems that

/// don't support timing

#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]

#[repr(C)]

pub struct SystemTickDiff {

    pub tick_diff: u64,

}

impl SystemTickDiff {

    /// Divide duration A by duration B.

    /// Returns `Inf` or `NaN` if `other` is zero.

    // tick counts -> f64 for the ratio; precision only degrades past 2^53 ticks.

    #[allow(clippy::cast_precision_loss)]

}

/// Duration represented as seconds + nanoseconds (mirrors `std::time::Duration`).

#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]

#[repr(C)]

pub struct SystemTimeDiff {

    pub secs: u64,

    pub nanos: u32,

}

impl SystemTimeDiff {

    /// Divide duration A by duration B.

    /// Returns `Inf` or `NaN` if `other` is zero.

    // secs (u64) -> f64 loses precision only past 2^53 seconds (~285M years).

    #[allow(clippy::cast_precision_loss)]

}

#[cfg(feature = "std")]

impl From<StdDuration> for SystemTimeDiff {

}

#[cfg(feature = "std")]

impl From<SystemTimeDiff> for StdDuration {

}

const MILLIS_PER_SEC: u64 = 1_000;

const NANOS_PER_MILLI: u32 = 1_000_000;

const NANOS_PER_SEC: u32 = 1_000_000_000;

impl SystemTimeDiff {

    /// Creates a duration from whole seconds.

    /// Creates a duration from milliseconds.

    /// Creates a duration from nanoseconds.

    // const fn (no const TryFrom); `nanos % NANOS_PER_SEC` is always < 10^9, which

    // fits u32, so the narrowing cast cannot truncate.

    #[allow(clippy::cast_possible_truncation)]

    /// Creates a duration from a `u128` nanosecond count, saturating at the

    /// largest representable duration instead of wrapping.

    ///

    /// Needed because [`Duration::as_nanos`] is `u128`: a tick count near

    /// `u64::MAX` converts to ~3e26 ns, far past what `u64` nanoseconds hold.

    // `nanos % NANOS_PER_SEC` is always < 10^9 and `secs` is range-checked above,

    // so neither narrowing cast can truncate. `as` widenings rather than `From`

    // because this is a `const fn`.

    #[allow(clippy::cast_possible_truncation, clippy::cast_lossless)]

        } else {

        }

    /// Adds two durations, returning None on overflow.

                }

        } else {

        }

    /// Returns the total duration in milliseconds.

    ///

    /// Saturates at `u64::MAX` instead of overflow-panicking for enormous

    /// `secs` values (`secs * 1000` overflows around ~1.8e16 seconds).

    /// Converts to `std::time::Duration`.

    #[cfg(feature = "std")]

}

/// Bridge from the CSS-level duration to the engine-level one, preserving the

/// unit.

///

/// This is the join that makes a CSS `5t` mean five FRAMES all the way down to

/// the timer: `ms`/`s` become `Duration::System`, `t` becomes `Duration::Tick`.

/// Collapsing ticks to milliseconds here would put the wall clock back in the

/// path and make "advance exactly 5 ticks, assert the 5th frame flipped"

/// untestable again.

impl From<azul_css::props::basic::time::CssDuration> for Duration {

        use azul_css::props::basic::time::CssDurationUnit;

        }

}

impl_option!(

    Instant,

    OptionInstant,

    copy = false,

    [Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash]

);

impl_option!(

    Duration,

    OptionDuration,

    [Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash]

);

#[allow(variant_size_differences)] // repr(C,u8) FFI enum: boxing the large variant would change the C ABI (api.json bindings); size disparity accepted

/// Message that can be sent from the main thread to the Thread using the `ThreadId`.

///

/// The thread can ignore the event.

#[derive(Debug, Clone, PartialEq, PartialOrd, Eq, Ord, Hash)]

#[repr(C, u8)]

pub enum ThreadSendMsg {

    /// The thread should terminate at the nearest

    TerminateThread,

    /// Next frame tick

    Tick,

    /// Custom data

    Custom(RefAny),

}

impl_option!(

    ThreadSendMsg,

    OptionThreadSendMsg,

    copy = false,

    [Debug, Clone, PartialEq, PartialOrd, Eq, Ord, Hash]

);

/// Channel endpoint for receiving messages from the main thread in a background thread.

///

/// Thread-safe wrapper around the receiver end of a message channel.

#[derive(Debug)]

#[repr(C)]

pub struct ThreadReceiver {

    #[cfg(feature = "std")]

    pub ptr: Box<Arc<Mutex<ThreadReceiverInner>>>,

    #[cfg(not(feature = "std"))]

    pub ptr: *const c_void,

    pub run_destructor: bool,

    /// For FFI: stores the foreign callable (e.g., `PyFunction`)

    pub ctx: OptionRefAny,

}

impl Clone for ThreadReceiver {

}

impl Drop for ThreadReceiver {

}

impl ThreadReceiver {

    /// Creates a new receiver (no-op on no_std).

    #[cfg(not(feature = "std"))]

    pub fn new(_t: ThreadReceiverInner) -> Self {

        Self {

            ptr: core::ptr::null(),

            run_destructor: false,

            ctx: OptionRefAny::None,

        }

    }

    /// Creates a new receiver wrapping the inner channel.

    #[cfg(feature = "std")]

    /// Get the FFI context (e.g., Python callable)

    /// Receives a message (returns None on no_std).

    #[cfg(not(feature = "std"))]

    pub fn recv(&mut self) -> OptionThreadSendMsg {

        None.into()

    }

    /// Receives a message from the main thread, if available.

    #[cfg(feature = "std")]

        };

}

/// Inner receiver state containing the actual channel and callbacks.

#[derive(Debug)]

#[cfg_attr(not(feature = "std"), derive(PartialEq, PartialOrd, Eq, Ord))]

#[repr(C)]

pub struct ThreadReceiverInner {

    #[cfg(feature = "std")]

    pub ptr: Box<Receiver<ThreadSendMsg>>,

    #[cfg(not(feature = "std"))]

    pub ptr: *const c_void,

    pub recv_fn: ThreadRecvCallback,

    pub destructor: ThreadReceiverDestructorCallback,

}

#[cfg(not(feature = "std"))]

unsafe impl Send for ThreadReceiverInner {}

#[cfg(feature = "std")]

impl core::hash::Hash for ThreadReceiverInner {

}

#[cfg(feature = "std")]

impl PartialEq for ThreadReceiverInner {

}

#[cfg(feature = "std")]

impl Eq for ThreadReceiverInner {}

#[cfg(feature = "std")]

impl PartialOrd for ThreadReceiverInner {

}

#[cfg(feature = "std")]

impl Ord for ThreadReceiverInner {

}

impl Drop for ThreadReceiverInner {

}

/// Get the current system type, equivalent to `std::time::Instant::now()`, except it

/// also works on systems that don't have a clock (such as embedded timers)

pub type GetSystemTimeCallbackType = extern "C" fn() -> Instant;

#[repr(C)]

pub struct GetSystemTimeCallback {

    pub cb: GetSystemTimeCallbackType,

}

impl_callback_simple!(GetSystemTimeCallback);

/// Default implementation that gets the current system time.

///

/// On WASM targets `std::time::Instant::now()` panics, so we fall back to

/// a zero-tick instant instead.

#[cfg(all(feature = "std", not(target_arch = "wasm32")))]

    // Honours the injectable E2E test clock (see TEST_CLOCK_OFFSET_MS).

/// Fallback for WASM (where `Instant::now()` panics) and no-std targets.

#[cfg(any(not(feature = "std"), target_arch = "wasm32"))]

pub extern "C" fn get_system_time_libstd() -> Instant {

    Instant::Tick(SystemTick::new(0))

}

/// Callback to check if a thread has finished execution.

pub type CheckThreadFinishedCallbackType =

    extern "C" fn(/* dropcheck */ *const c_void) -> bool;

/// Wrapper for thread completion check callback.

#[repr(C)]

pub struct CheckThreadFinishedCallback {

    pub cb: CheckThreadFinishedCallbackType,

}

impl_callback_simple!(CheckThreadFinishedCallback);

/// Callback to send a message to a background thread.

pub type LibrarySendThreadMsgCallbackType =

    extern "C" fn(/* Sender<ThreadSendMsg> */ *const c_void, ThreadSendMsg) -> bool;

/// Wrapper for thread message send callback.

#[repr(C)]

pub struct LibrarySendThreadMsgCallback {

    pub cb: LibrarySendThreadMsgCallbackType,

}

impl_callback_simple!(LibrarySendThreadMsgCallback);

/// Callback for a running thread to receive messages from the main thread.

pub type ThreadRecvCallbackType =

    extern "C" fn(/* receiver.ptr */ *const c_void) -> OptionThreadSendMsg;

/// Wrapper for thread message receive callback.

#[repr(C)]

pub struct ThreadRecvCallback {

    pub cb: ThreadRecvCallbackType,

}

impl_callback_simple!(ThreadRecvCallback);

/// Callback to destroy a `ThreadReceiver`.

pub type ThreadReceiverDestructorCallbackType = extern "C" fn(*mut ThreadReceiverInner);

/// Wrapper for thread receiver destructor callback.

#[repr(C)]

pub struct ThreadReceiverDestructorCallback {

    pub cb: ThreadReceiverDestructorCallbackType,

}

impl_callback_simple!(ThreadReceiverDestructorCallback);

#[cfg(test)]

#[allow(clippy::float_cmp)] // exact-value assertions on interpolation results

mod tests {

    use super::*;