@ascentbv/ts-common - v1.0.165
    Preparing search index...

    Class TimerUtilAbstract

    Index

    Constructors

    constructor

    Methods

    runTimeout runInterval nextTick runLatestTimeout clearLatestTimeout getSchedulerMetrics clear clearAllNamedIntervals getNamedIntervalStats listIntervals

    Constructors

    Methods

    • Schedule a one-off callback after a specified delay (in ticks).

      Parameters

      • callback: () => void

        Function to execute after the delay.

      • delay: number

        Delay in Ticks (20 ticks = 1 second).

      • OptionalprofileLabel: string

        Optional profiling label. If provided, the callback is wrapped with DebugTimerUtil.start / DebugTimerUtil.stop.

      Returns number

      The timeout ID from system.runTimeout.

      // Run once after 40 ticks (2 seconds)
      TimerUtil.runTimeout(() => doSomethingOnce(), 40);

      // Run once after 20 ticks with profiling
      TimerUtil.runTimeout(() => showcaseProfiling(), 20, "showcaseProfiling.once");
      • The delay is measured in game ticks (20 ticks = 1 second).
      • If profileLabel is provided, the callback is wrapped with DebugTimerUtil.start / DebugTimerUtil.stop.
      • Delay <= 1 runs immediately when triggered.
      • Delay > 1 may be load-spread across nearby ticks during heavy contention.
      • Spreadable timeouts are routed by delay: 2-10 ticks prefer the short lane, >10 ticks use the long lane.
      • Spreadable timeouts include a small deterministic jitter (0-1 tick) to reduce synchronized burst execution.
      • Throws if callback is not a function or delay is not a non-negative number.

    • Repeats a callback every delay ticks.

      • Named interval: provide options.name to allow later control via TimerUtil.clear, statistics via TimerUtil.getNamedIntervalStats, and to prevent accidental duplicates.
      • Anonymous interval: omit options.name. Useful for quick, fire-and-forget repeating work.

      Parameters

      Returns number

      The interval ID from system.runInterval.

      // Anonymous interval, every 20 ticks
      const id = TimerUtil.runInterval(() => everySecondThisRuns(), 20);

      // Named interval with profiling and an immediate first run
      TimerUtil.runInterval(() => refreshStats(), 10, {
          name: "StatsRefresh",
          beginImmediately: true,
          profile: true, // uses name as profile label
      });

      // Replace an existing named interval
      TimerUtil.runInterval(() => rescan(), 5, { name: "Scanner", force: true, profile: "scanner" });
      • The delay is measured in game ticks (20 ticks = 1 second).
      • If beginImmediately is true, the callback runs once before scheduling.
      • Profiling uses options.profile:
        • true > uses the interval's name (or "anonymous_interval" for anonymous).
        • string > uses the provided label.
      • Delay <= 1 runs immediately when triggered.
      • Delay > 1 may be load-spread across nearby ticks during heavy contention.
      • For named intervals, creating a duplicate without force: true throws.
      • Throws if callback is not a function or delay is not a non-negative number.

    • Repeats a callback every delay ticks.

      • Named interval: provide options.name to allow later control via TimerUtil.clear, statistics via TimerUtil.getNamedIntervalStats, and to prevent accidental duplicates.
      • Anonymous interval: omit options.name. Useful for quick, fire-and-forget repeating work.

      Parameters

      Returns number

      The interval ID from system.runInterval.

      // Anonymous interval, every 20 ticks
      const id = TimerUtil.runInterval(() => everySecondThisRuns(), 20);

      // Named interval with profiling and an immediate first run
      TimerUtil.runInterval(() => refreshStats(), 10, {
          name: "StatsRefresh",
          beginImmediately: true,
          profile: true, // uses name as profile label
      });

      // Replace an existing named interval
      TimerUtil.runInterval(() => rescan(), 5, { name: "Scanner", force: true, profile: "scanner" });
      • The delay is measured in game ticks (20 ticks = 1 second).
      • If beginImmediately is true, the callback runs once before scheduling.
      • Profiling uses options.profile:
        • true > uses the interval's name (or "anonymous_interval" for anonymous).
        • string > uses the provided label.
      • Delay <= 1 runs immediately when triggered.
      • Delay > 1 may be load-spread across nearby ticks during heavy contention.
      • For named intervals, creating a duplicate without force: true throws.
      • Throws if callback is not a function or delay is not a non-negative number.

    • Schedule a callback on the next tick.

      Parameters

      Returns number

      The ID from system.run.

      // Defer work to after the current tick completes
      TimerUtil.nextTick(() => finalize());
      • The scheduled work runs in the next game tick, after the current tick completes.
      • If profileLabel is provided, the callback is wrapped with DebugTimerUtil.start / DebugTimerUtil.stop.
      • Next-tick callbacks are treated as spreadable and routed to the short lane to prioritize responsiveness.
      • Throws if callback is not a function.

    • Schedule a timeout by key where the latest schedule replaces any previous pending timeout.

      Parameters

      • key: string

        Logical key for deduplication.

      • callback: () => void

        Callback to run.

      • delay: number

        Delay in ticks.

      • OptionalprofileLabel: string

        Optional profiling label.

      Returns number

      The timeout ID for the latest scheduled callback.

      // Before: many queued timeouts can stack stale work
      TimerUtil.runTimeout(() => refreshUi(), 20);

      // After: only the latest request survives
      TimerUtil.runLatestTimeout("ui.refresh", () => refreshUi(), 20);

    • Clear a scheduled interval by name (named intervals) or by ID (anonymous or named).

      Parameters

      • idOrName: string | number

        The interval ID (from runInterval) or the name provided in NamedIntervalOptions.

      Returns void

      // Clear by ID
      const id = TimerUtil.runInterval(() => tick(), 20);
      TimerUtil.clear(id);

      // Clear by name
      TimerUtil.runInterval(() => refresh(), 10, { name: "StatsRefresh" });
      TimerUtil.clear("StatsRefresh");
      • If a string is passed, it is treated as the name of a named interval.
      • If a number is passed, it is treated as the interval ID returned by runInterval.
      • Clearing an interval that does not exist does nothing.

    • Clear all currently active named intervals.

      Returns void

      // Useful during shutdown/reload hooks
      TimerUtil.clearAllNamedIntervals();
      • Only affects intervals created with a name in NamedIntervalOptions.
      • Useful for cleanup during shutdown or reload events.

    • Get rolling performance statistics for a named interval.

      Parameters

      • name: string

        The interval name used when creating it.

      Returns NamedIntervalStats | undefined

      NamedIntervalStats with averageTime and maxTime (ms) computed over the recent execution window, or undefined if no such interval exists.

      const stats = TimerUtil.getNamedIntervalStats("StatsRefresh");
      if (stats) {
          DevUtil.logAll("Debug",
              `avg=${stats.averageTime.toFixed(2)}ms max=${stats.maxTime}ms calls=${stats.totalCalls}`);
      }
      • The rolling window is kept in elapsedTimes and is capped at 40 entries.
      • Times are measured using Date.now() around the callback execution.
      • Returns undefined if no active named interval exists with the given name.

    • List the names of all active named intervals.

      Returns string[]

      An array of names corresponding to active named intervals.

      for (const name of TimerUtil.listIntervals()) {
          DevUtil.logAll("Debug", `Active interval: ${name}`);
      }
      • Only lists currently active named intervals.
      • The returned array is a snapshot and will not update if intervals are added or removed.

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods