omni.flux.job_queue.widget#

  • SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.

  • SPDX-License-Identifier: Apache-2.0

  • Licensed under the Apache License, Version 2.0 (the “License”);

  • you may not use this file except in compliance with the License.

  • You may obtain a copy of the License at

  • https://www.apache.org/licenses/LICENSE-2.0

  • Unless required by applicable law or agreed to in writing, software

  • distributed under the License is distributed on an “AS IS” BASIS,

  • WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

  • See the License for the specific language governing permissions and

  • limitations under the License.

class omni.flux.job_queue.widget.ApplyHandler#

Base class for handling job result application.

ApplyHandlers are responsible for taking completed job results and applying them (e.g., to a USD stage). Each handler is registered for specific job types.

Subclass this and implement can_handle() and apply() for your job type.

abstract async apply(
interface: QueueInterface,
job: Job,
) → None#

Apply the job results.

Parameters:

  • interface – The job queue interface for accessing job events/results.

  • job – The completed job to apply results from.

abstract classmethod can_handle(
job: Job,
) → bool#

Check if this handler can process the given job type.

get_apply_context(
job: Job,
) → dict[str, Any]#

Get context information for tracking applied state.

Override this to provide context-specific information that determines whether the job has already been applied (e.g., current USD edit target).

Returns an empty dict by default, meaning “applied once = applied everywhere”.

class omni.flux.job_queue.widget.ApplyHandlerRegistry#

Registry for job apply handlers.

Handlers are checked in registration order. The first handler that can_handle() the job type is used.

This class provides the can_apply, has_been_applied, and apply functions that can be passed to CallbackExecutor.

async classmethod apply(
interface: QueueInterface,
job: Job,
) → None#

Apply job results using the appropriate handler.

Also records a CallbackApplied event for has_been_applied tracking.

Raises ValueError if no handler is registered for the job type.

classmethod can_apply(
job: Job,
) → bool#

Check if any registered handler can apply this job.

classmethod clear() → None#

Remove all registered handlers.

classmethod get_handler(
job: Job,
) → ApplyHandler | None#

Get a handler instance for the given job, or None if no handler matches.

classmethod has_been_applied(
interface: QueueInterface,
job: Job,
) → bool#

Check if a job has already been applied in the current context.

This checks for a CallbackApplied event and compares its context with the current context from the handler.

classmethod register(
handler_class: type[ApplyHandler],
) → None#

Register an apply handler.

classmethod unregister(
handler_class: type[ApplyHandler],
) → None#

Unregister an apply handler.

class omni.flux.job_queue.widget.ApplyState(value)#

State of a job apply operation.

class omni.flux.job_queue.widget.CallbackApplied(context: dict = <factory>)#

Event recorded when job results have been applied.

The context dict can be used to track different application contexts, allowing the same job to be applied multiple times in different contexts (e.g., different USD edit targets).

class omni.flux.job_queue.widget.CallbackExecutor(
interface: QueueInterface,
apply_handler: Callable[[QueueInterface, Job], None | Coroutine[Any, Any, None]],
can_apply: Callable[[Job], bool],
has_been_applied: Callable[[QueueInterface, Job], bool],
)#

Manages the execution of job apply handlers on the main thread.

This class ensures that apply handlers are properly executed on Kit’s main asyncio event loop, which is required for USD commands and UI operations.

Callbacks are queued and executed sequentially - only one callback runs at a time.

Thread-safe: Can be called from any thread; handlers will be scheduled on the main event loop.

Parameters:

  • interface – The job queue interface.

  • apply_handler – Function to apply job results. Required.

  • can_apply – Function to check if a job can be applied. Required.

  • has_been_applied – Function to check if job was already applied. Required.

can_apply(
job: Job,
) → bool#

Check if a job can be applied.

cancel(job_id: UUID) → bool#

Cancel a pending or running callback execution.

Returns True if the execution was cancelled, False if it wasn’t found or already completed.

clear_completed() → None#

Remove all completed, failed, or cancelled executions from tracking.

get_execution_state(
job_id: UUID,
) → ApplyState | None#

Get the current execution state for a job, or None if not tracked.

has_been_applied(
job: Job,
) → bool#

Check if a job has already been applied.

is_running(job_id: UUID) → bool#

Check if a callback is currently running for the given job.

schedule(
job: Job,
) → None#

Schedule a job for apply execution on the main thread.

Jobs are queued and executed sequentially - only one runs at a time. If a job is already queued/running or has been applied, it will be skipped.

Thread-safe: uses a lock to prevent race conditions when called from multiple threads.

subscribe_state_changed(
callback: Callable[[UUID, ApplyState, Exception | None], None],
) → EventSubscription#

Subscribe to callback execution state changes.

class omni.flux.job_queue.widget.QueueItem(row: Row)#
class omni.flux.job_queue.widget.QueueItemDelegate(model: QueueModel)#
build_header(
self: omni.ui._ui.AbstractItemDelegate,
column_id: int = 0,
) → None#

This pure abstract method must be reimplemented to generate custom widgets for the header table.

build_widget(
self: omni.ui._ui.AbstractItemDelegate,
model: omni.ui._ui.AbstractItemModel,
item: omni.ui._ui.AbstractItem = None,
index: int = 0,
level: int = 0,
expanded: bool = False,
) → None#

This pure abstract method must be reimplemented to generate custom widgets for specific item in the model.

class omni.flux.job_queue.widget.QueueModel(
interface: QueueInterface,
callback_executor: CallbackExecutor,
)#

Model for the job queue TreeView.

This model manages the list of queue items and delegates apply execution to a CallbackExecutor instance.

The model performs incremental updates to preserve selection state and avoid jarring UI rebuilds. Items are tracked by job_id, and only changed items trigger UI updates.

property callback_executor: CallbackExecutor#

The callback executor used by this model.

delete_selected()#

Delete the selected jobs.

This method deletes jobs from the database immediately and schedules file cleanup to run in the background. Rows being deleted will display a “Deleting…” state until cleanup is complete.

get_delete_state(
job_id: UUID,
) → DeleteState | None#

Get the current delete state for a job, or None if not being deleted.

get_item_children(
self: omni.ui._ui.AbstractItemModel,
parentItem: omni.ui._ui.AbstractItem = None,
) → List[omni.ui._ui.AbstractItem]#

Returns the vector of items that are nested to the given parent item.

### Arguments:

id :

The item to request children from. If it’s null, the children of root will be returned.

get_item_value_model_count(
self: omni.ui._ui.AbstractItemModel,
item: omni.ui._ui.AbstractItem = None,
) → int#

Returns the number of columns this model item contains.

is_deleting(job_id: UUID) → bool#

Check if a job is currently being deleted.

refresh(force=False, run_auto_apply=True)#

Refresh the queue items from the database.

This method performs incremental updates to preserve selection state: - Existing items are updated in-place if their content changed - New items are added to the list - Removed items are deleted from the list - Only triggers full UI rebuild when items are added/removed

Parameters:

  • force – If True, trigger UI update for all changed items even if structure unchanged.

  • run_auto_apply – If True and auto_apply is enabled, run auto-apply after refresh. Set to False when refreshing just to update UI state.

remove_item(
self: omni.ui._ui.AbstractItemModel,
item: omni.ui._ui.AbstractItem,
) → None#

Removes the item from the model. There is no parent here because we assume that the reimplemented model deals with its data and can figure out how to remove this item.

schedule_callback(
item: QueueItem,
) → None#

Schedule a job’s apply for execution.

This delegates to the CallbackExecutor which ensures proper main-thread execution.

subscribe_delete_state_changed(
func: Callable[[UUID, DeleteState], None],
) → EventSubscription#

Subscribe to job deletion state changes.

class omni.flux.job_queue.widget.QueueView(
model: QueueModel,
delegate: QueueItemDelegate,
**kwargs,
)#
class omni.flux.job_queue.widget.QueueWidget(
interface: QueueInterface,
callback_executor: CallbackExecutor,
executor: JobExecutor | None = None,
scheduler: JobScheduler | None = None,
)#

Complete job queue widget with controls and job list.

Includes: - Start/Stop scheduler controls - Manual refresh button - Delete selected button - Auto-apply toggle - Apply selected button - Job list with details panel

Parameters:

  • interface – The job queue interface.

  • callback_executor – Executor for applying job results.

  • executor – Optional custom executor for job execution.

  • scheduler – Optional custom scheduler. Created automatically if not provided.

stop_scheduler() → None#

Stop the scheduler from picking up new jobs.

The scheduler will finish the currently executing job (if any) before fully stopping.