feat: allow custom priority for workers

[edusperoni]

Summary by CodeRabbit

• New Features

  • Workers now support Quality of Service (QoS) configuration through an optional iosPriority parameter, enabling fine-tuned thread priority management.

• Bug Fixes

  • Improved error handling for uncaught exceptions in worker threads to prevent duplicate error reporting and ensure proper exception propagation.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR introduces quality-of-service (QoS) parameter support for NativeScript worker threads. The Worker constructor now accepts an optional iosPriority option string, which is mapped to a numeric QoS value and propagated through WorkerWrapper::Start() to the underlying NSBlockOperation scheduling, allowing finer control over background thread priority on iOS.

Changes

Worker Thread Quality of Service Support

Layer / File(s)	Summary
Worker QoS API Contract NativeScript/runtime/DataWrapper.h	WorkerWrapper::Start() signature extended to accept optional int qualityOfService = -1 parameter.
Header Reorganization and Formatting NativeScript/runtime/DataWrapper.h	Header includes reordered; wrapper class declarations reformatted for consistency without changing public method signatures or behavior.
iOS Priority Parsing and QoS Propagation NativeScript/runtime/Worker.mm	Constructor callback parses optional iosPriority string from options object and maps known priority strings to numeric QoS values; worker startup call passes computed QoS to Start().
QoS Scheduling Implementation NativeScript/runtime/WorkerWrapper.mm	Start() implementation creates NSBlockOperation for background looper and conditionally applies qualityOfService property when parameter is non-negative before enqueueing.
Error Handling Refinements NativeScript/runtime/Worker.mm, NativeScript/runtime/WorkerWrapper.mm	Debug-mode jsErrorOccurred handling refactored to dispatch asynchronously then clear flag to prevent duplicate reporting; PassUncaughtExceptionFromWorkerToMain signature reformatted.
Code Comments and Namespace Closure NativeScript/runtime/Worker.mm, NativeScript/runtime/WorkerWrapper.mm	Namespace-closing comments added for documentation.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

A worker thread, once plain and free,
Now prioritized with QoS decree!
🐇 Maps iOS priority strings with care,
Schedules tasks with quality to spare.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: allow custom priority for workers' accurately describes the main change: adding a qualityOfService parameter to enable custom worker priority configuration.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@NativeScript/runtime/Worker.mm`:
- Around line 114-120: The ios QoS mapping in the priority branch (checks for
"userInteractive", "userInitiated", "default", "utility") incorrectly hardcodes
hex literals; change those branches to use the NSQualityOfService constants
(e.g., NSQualityOfServiceUserInteractive, NSQualityOfServiceUserInitiated,
NSQualityOfServiceDefault/NSQualityOfServiceUtility) and modify the "default"
branch so it does not force an explicit QoS value (i.e., leave qos unset or set
to the sentinel used by worker->Start(..., qos) to indicate “do not set QoS”);
update the code around worker->Start(..., qos) to pass that sentinel when
priority == "default" and ensure all other branches use the named
NSQualityOfService* constants instead of hex literals.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 236f41b7-1842-487f-8583-141ad44b2b77

📥 Commits

Reviewing files that changed from the base of the PR and between ecd3598 and 7fc278f.

📒 Files selected for processing (3)

• NativeScript/runtime/DataWrapper.h
• NativeScript/runtime/Worker.mm
• NativeScript/runtime/WorkerWrapper.mm

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🌐 Web query:

What are the official raw values for the iOS NSQualityOfService enum, including NSQualityOfServiceDefault?

💡 Result:

I couldn’t find an authoritative Apple source that states the integer raw values (e.g., via a “raw value” table or enum definition) for the iOS NSQualityOfService enum cases, including NSQualityOfServiceDefault. What the official Apple docs do provide is the set of QoS levels (UserInteractive, UserInitiated, Utility, Background) and that “default” means “no explicit quality of service information / treated as default.” Apple’s Energy Efficiency Guide for iOS Apps states that when no QoS information is assigned, work is treated as default, and lists only the primary QoS constants (UserInteractive/UserInitiated/Utility/Background) as the developer-facing choices [1]. Apple’s Swift doc for the “QualityOfService.default” case also describes it as “Indicates no explicit quality of service information” and clarifies how the system picks an appropriate QoS when “default” is used (again, without giving a raw integer) [2]. So, while I can confirm the semantic meaning of “default,” I cannot (from the sources found) provide the exact official integer raw values for NSQualityOfService (including NSQualityOfServiceDefault).

Citations:

• 1: https://developer.apple.com/library/archive/documentation/Performance/Conceptual/EnergyGuide-iOS/PrioritizeWorkWithQoS.html
• 2: https://sosumi.ai/documentation/Foundation/QualityOfService/default

---

Fix QoS mapping for iosPriority: "default" in NativeScript/runtime/Worker.mm

Apple defines QoS “default” as “no explicit quality-of-service information” (system selects an appropriate QoS). The current mapping forces an explicit hardcoded value (qos = 0x15) for "default", which risks overriding the intended semantics. Replace the hardcoded hex QoS literals with NSQualityOfService* constants, and ensure "default" results in “do not set QoS” behavior (or the equivalent sentinel/path supported by the worker->Start(..., qos) contract).

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@NativeScript/runtime/Worker.mm` around lines 114 - 120, The ios QoS mapping
in the priority branch (checks for "userInteractive", "userInitiated",
"default", "utility") incorrectly hardcodes hex literals; change those branches
to use the NSQualityOfService constants (e.g.,
NSQualityOfServiceUserInteractive, NSQualityOfServiceUserInitiated,
NSQualityOfServiceDefault/NSQualityOfServiceUtility) and modify the "default"
branch so it does not force an explicit QoS value (i.e., leave qos unset or set
to the sentinel used by worker->Start(..., qos) to indicate “do not set QoS”);
update the code around worker->Start(..., qos) to pass that sentinel when
priority == "default" and ensure all other branches use the named
NSQualityOfService* constants instead of hex literals.