TrackerBackend

ceramic.TrackerBackend (Class)

Backend adapter that bridges the Tracker observable framework with Ceramic's backend services.

TrackerBackend provides a unified interface for the Tracker framework to access platform-specific functionality through Ceramic's backend system. It handles threading, persistence, logging, timers, and file system operations in a platform-agnostic way.

This class is used internally by the Tracker framework and typically doesn't need to be accessed directly by application code. It ensures that observable objects and reactive systems can leverage Ceramic's full feature set.

Key responsibilities:

  • Scheduling: Immediate callbacks and background execution
  • Persistence: String-based key-value storage
  • Logging: Warning, error, and success messages
  • Threading: Background and main thread execution
  • Timers: Intervals and delayed callbacks
  • File System: Storage directory and path operations

Instance Members

onceImmediate(handleImmediate: Function): Void

Schedules a callback to run on the next frame or event loop iteration.

The callback is queued and will be executed during the next update cycle. This is useful for deferring operations that should happen after the current call stack completes.

Name Type Description
handleImmediate Function The callback to schedule for immediate execution

readString(key: String): String

Read a string for the given key

Name Type Description
key String the key to use
Returns Description
String String or null of no string was found

saveString(key: String, str: String): Bool

Save a string for the given key

Name Type Description
key String the key to use
str String the string to save
Returns Description
Bool Bool true if the save was successful

appendString(key: String, str: String): Bool

Append a string on the given key. If the key doesn't exist, creates a new one with the string to append.

Name Type Description
key String the key to use
str String the string to append
Returns Description
Bool Bool true if the save was successful

warning(message: Dynamic, ?pos: Null<haxe.PosInfos>): Void

Log a warning message

Name Type Default Description
message Dynamic the warning message
pos Null<haxe.PosInfos> (optional)

error(error: Dynamic, ?pos: Null<haxe.PosInfos>): Void

Log an error message

Name Type Default Description
error Dynamic the error message
pos Null<haxe.PosInfos> (optional)

success(message: Dynamic, ?pos: Null<haxe.PosInfos>): Void

Log a success message

Name Type Default Description
message Dynamic the success message
pos Null<haxe.PosInfos> (optional)

runInBackground(callback: Function): Void

Executes a callback on a background thread when available.

On platforms with threading support, the callback runs on a separate thread. On single-threaded platforms (like web), the callback is queued and executed on the main thread to maintain compatibility.

Use this for CPU-intensive operations that shouldn't block the UI.

Name Type Description
callback Function The function to execute in the background

runInMain(callback: Function): Void

Schedules a callback to run on the main thread.

If called from a background thread, the callback is queued for execution on the main thread. If already on the main thread, the callback may be executed immediately or queued depending on the implementation.

Essential for updating UI or accessing main-thread-only resources from background threads.

Name Type Description
callback Function The function to execute on the main thread

interval(owner: Entity, seconds: Float, callback: Function): Function

Execute a callback periodically at the given interval in seconds.

Name Type Description
owner Entity The entity that owns this interval
seconds Float The time in seconds between each call
callback Function The callback to call
Returns Description
Function Void->Void A callback to cancel the interval

delay(owner: Entity, seconds: Float, callback: Function): Function

Execute a callback after the given delay in seconds.

Name Type Description
owner Entity The entity that owns this delayed call
seconds Float The time in seconds of delay before the call
callback Function The callback to call
Returns Description
Function Void->Void A callback to cancel the delayed call

storageDirectory(): Null<String>

Gets the platform-specific storage directory for persistent data.

Returns a writable directory path where the application can store user data, save files, and preferences. The location varies by platform:

  • Desktop: User's app data directory
  • Mobile: App's private storage
  • Web: May return null (use other storage methods)
Returns Description
Null<String> The storage directory path, or null if not available

pathJoin(paths: Array<String>): String

Joins multiple path segments into a single path string.

Handles platform-specific path separators and resolves relative paths. Useful for building file paths in a cross-platform way.

Example:

pathJoin(["assets", "images", "player.png"]); // "assets/images/player.png"
Name Type Description
paths Array<String> Array of path segments to join
Returns Description
String The combined path with appropriate separators

new(): Void

Creates a new TrackerBackend instance. Initializes the background queue for task scheduling.

Private Members

backgroundQueue: BackgroundQueue

Queue for managing background task execution. Handles scheduling and execution of tasks on background threads when available.