mobalazs / rotor-framework / 29758339845

' =========================================================================

' ▗▄▄▖  ▗▄▖▗▄▄▄▖▗▄▖ ▗▄▄▖     ▗▄▄▄▖▗▄▄▖  ▗▄▖ ▗▖  ▗▖▗▄▄▄▖▗▖ ▗▖ ▗▄▖ ▗▄▄▖ ▗▖ ▗▖

' ▐▌ ▐▌▐▌ ▐▌ █ ▐▌ ▐▌▐▌ ▐▌    ▐▌   ▐▌ ▐▌▐▌ ▐▌▐▛▚▞▜▌▐▌   ▐▌ ▐▌▐▌ ▐▌▐▌ ▐▌▐▌▗▞▘

' ▐▛▀▚▖▐▌ ▐▌ █ ▐▌ ▐▌▐▛▀▚▖    ▐▛▀▀▘▐▛▀▚▖▐▛▀▜▌▐▌  ▐▌▐▛▀▀▘▐▌ ▐▌▐▌ ▐▌▐▛▀▚▖▐▛▚▖

' ▐▌ ▐▌▝▚▄▞▘ █ ▝▚▄▞▘▐▌ ▐▌    ▐▌   ▐▌ ▐▌▐▌ ▐▌▐▌  ▐▌▐▙▄▄▖▐▙█▟▌▝▚▄▞▘▐▌ ▐▌▐▌ ▐▌

' Rotor Framework™

' Version 0.9.2

' © 2025-2026 Balázs Molnár — Apache License 2.0

' =========================================================================

' constants

import "engine/Constants.bs"

' engine

import "engine/providers/DispatcherProvider.bs"

import "engine/providers/Dispatcher.bs"

' base classes

import "base/DispatcherOriginal.bs"

import "base/DispatcherCrossThread.bs"

import "base/BaseReducer.bs"

import "base/CombinedReducer.bs"

import "base/BaseModel.bs"

import "base/BaseStack.bs"

' utils

import "utils/GeneralUtils.bs"

import "utils/NodeUtils.bs"

import "utils/ArrayUtils.bs"

namespace Rotor

    ' =====================================================================

    ' FrameworkTask - Task thread version of Rotor Framework for MVI

    '

    ' Task thread version of the Rotor Framework that enables cross-thread MVI

    ' (Model-View-Intent) architecture. This class manages state and dispatchers

    ' on a separate task thread, allowing heavy computations and state management

    ' to run off the render thread for better performance.

    '

    ' Configuration:

    '   - tasks (array, optional): List of additional task node names to synchronize with.

    '                             Allows multiple task threads to communicate and share

    '                             dispatchers across different threads.

    '

    ' USAGE NOTES:

    ' The FrameworkTask must be instantiated in the task's init() function and the sync()

    ' method MUST be called at the end of your task function to establish the message loop.

    '

    ' IMPORTANT: The sync() method creates an infinite loop that handles cross-thread

    ' communication and dispatcher synchronization. This call should be the LAST statement

    ' in your task function, after all dispatcher initialization.

    '

    ' Example:

    '   File: MyTask.task.bs

    '   import "pkg:/source/RotorFrameworkTask.bs"

    '   import "pkg:/source/MyDispatcher.bs"

    '

    '   sub init()

    '       m.top.functionName = "task"

    '       m.appFw = new Rotor.FrameworkTask({

    '           tasks: ["AnotherTask"]

    '       })

    '   end sub

    '

    '   sub task()

    '       m.fooDispatcher = createFooDispatcher()

    '       m.barDispatcher = createBarDispatcher()

    '       m.appFw.sync()

    '   end sub

    ' =====================================================================

    class FrameworkTask

        name = "Rotor Framework"

        version = "0.9.2"

        config = {

            tasks: invalid, ' optional

            debug: {

            }

        }

        threadType = Rotor.Const.ThreadType.TASK

        keepAlive = true

        ' helper vars

        taskNode as object

        renderQueue as object

        dispatcherProvider as object

        port as object

        sourceObjectRegistry = {} ' identity -> { dispatcherId, objectId, eventFilter }

        sourceObjectIdIndex = {} ' objectId -> identity (reverse index for unregistration)

        sharedSourceObjects = {} ' typeName -> { sourceObject, subscribers: [{ dispatcherId, eventFilter }] }

        nodeObserverRegistry = {} ' fieldId -> { dispatcherId, node } (SG-node field events routed to onSourceEvent)

        private _eventFilterFn = invalid as dynamic

        onTick as function

        ' ---------------------------------------------------------------------

        ' new - Initializes the FrameworkTask instance

        '

        ' Sets up the task thread dispatcher provider, message port, and

        ' global framework helper for cross-thread communication.

        '

        ' @param {object} config - Configuration object (see class documentation)

        '

        sub new(config = {} as object)

                threadType: m.threadType,

                frameworkInstance: m

            }

        end sub

        ' =====================================================================

        ' PUBLIC API

        ' =====================================================================

        ' =====================================================================

        ' ROUTER — Task → Render

        ' =====================================================================

        ' ---------------------------------------------------------------------

        ' sendStateToRender - Routes dispatcher state update to render thread

        '

        ' Called by DispatcherOriginal.exposeState(). Sends via the single

        ' __rotor__ channel on roRenderThreadQueue — zero rendezvous on task thread.

        '

        ' @param {string} dispatcherId - Dispatcher identifier

        ' @param {object} state - Current state AA

        '

        public sub sendStateToRender(dispatcherId as string, state as object)

                type: Rotor.Const.RouterMsgType.STATE,

                dispatcherId: dispatcherId,

                state: state

            })

        end sub

        ' ---------------------------------------------------------------------

        ' sendIntent - Routes a cross-thread intent dispatch (task → render thread)

        '

        ' Called by DispatcherCrossThread.dispatch() on the task thread. A task cannot

        ' write a foreign (render-owned) node's rotorSync field without a blocking

        ' rendezvous, so the intent is relayed to the render thread via the

        ' rendezvous-free __rotor__ channel (CopyMessage), symmetric with

        ' sendStateToRender. The render thread resolves the target dispatcher by id and

        ' re-dispatches locally (see RotorFramework.handleIntentMessage). Enables

        ' task → render and task → task intent dispatch.

        '

        ' Thread-neutral counterpart of Framework.sendIntent (render → task). Same

        ' signature so DispatcherCrossThread.dispatch() works unchanged from either

        ' thread. The node parameter is unused on the task side — the render thread

        ' resolves the target from its own registry by dispatcherId.

        '

        ' @param {object} node - Target dispatcher state node (unused on task side)

        ' @param {string} dispatcherId - Target dispatcher identifier

        ' @param {object} intent - Intent to dispatch

        '

        public sub sendIntent(node as object, dispatcherId as string, intent as object)

                type: Rotor.Const.RouterMsgType.INTENT,

                dispatcherId: dispatcherId,

                intent: intent

            })

        end sub

        ' ---------------------------------------------------------------------

        ' connectDispatcher - Creates a new dispatcher facade connection by ID

        '

        ' Each call creates a unique facade with its own listenerId and scope binding.

        ' Use facade.release() when done to clean up listeners.

        '

        ' @param {string} dispatcherId - Dispatcher identifier

        ' @returns {object} Dispatcher facade instance

        '

        public function connectDispatcher(dispatcherId as string) as object

        end function

        ' ---------------------------------------------------------------------

        ' dispatchTo - Dispatches an intent to a specific dispatcher by ID

        '

        ' @param {string} dispatcherId - Target dispatcher identifier

        ' @param {object} dispatchObject - Intent object to dispatch

        '

        public sub dispatchTo(dispatcherId as string, dispatchObject as object)

        end sub

        ' ---------------------------------------------------------------------

        ' getStateFrom - Gets current state from a specific dispatcher by ID

        '

        ' @param {string} dispatcherId - Target dispatcher identifier

        ' @param {dynamic} [mapStateToProps=invalid] - Optional state mapping function

        ' @returns {object} Current state from the target dispatcher

        '

        public function getStateFrom(dispatcherId as string, mapStateToProps = invalid as dynamic) as object

        end function

        ' ---------------------------------------------------------------------

        ' registerSourceObject - Creates and registers a source object for event routing

        '

        ' Creates a Roku source object by type name and auto-detects routing mode:

        '   - Identity-based: If sourceObject implements GetIdentity, each call creates

        '     a new instance with unique routing (roUrlTransfer, roChannelStore).

        '   - Broadcast (singleton): If sourceObject does NOT implement GetIdentity,

        '     first call creates the instance, subsequent calls return the shared instance

        '     and add the dispatcher as a subscriber (roDeviceInfo, roInput, roAppManager).

        '

        ' @param {string} typeName - Roku object type name (e.g. "roUrlTransfer", "roDeviceInfo")

        ' @param {string} dispatcherId - Dispatcher ID that will handle events

        ' @param {function} eventFilter - Optional filter function. Receives msg, returns boolean.

        ' @returns {object} The created (or shared) source object

        '

        public function registerSourceObject(typeName as string, dispatcherId as string, eventFilter = invalid as dynamic) as object

                ' Identity-based: unique per call

                    dispatcherId: dispatcherId,

                    objectId: objectId,

                    eventFilter: eventFilter

                }

            else

                    ' Existing — add subscriber, discard new object

                        dispatcherId: dispatcherId,

                        eventFilter: eventFilter

                    })

                else

                        sourceObject: sourceObject,

                        subscribers: [{

                            dispatcherId: dispatcherId,

                            eventFilter: eventFilter

                        }]

                    }

                end if

            end if

        end function

        ' ---------------------------------------------------------------------

        ' unregisterSourceObject - Unregisters a source object

        '

        ' Identity-based objects: removes by identity from registry.

        ' Broadcast objects: removes dispatcher subscriber, cleans up if no subscribers remain.

        '

        ' @param {object} sourceObject - The source object to unregister

        ' @param {string} dispatcherId - Dispatcher ID that owns this registration

        '

        public sub unregisterSourceObject(sourceObject as object, dispatcherId as string)

                ' Identity-based: remove by identity

                end if

                end if

            else

                        end if

                    end for

                    end if

                end if

            end if

        end sub

        ' ---------------------------------------------------------------------

        ' registerNodeObserver - Routes a task-created SG node's field events to a dispatcher

        '

        ' SG nodes (e.g. ChannelStore) deliver results via observed fields (roSGNodeEvent).

        ' The task loop reserves SG-node field events for the cross-thread state protocol

        ' (fieldId = dispatcherId), so an unregistered field would be silently dropped.

        ' This registry claims a fieldId and routes its events to the owning dispatcher's

        ' onSourceEvent instead.

        '

        ' NOTE: the fieldId must not collide with a dispatcher id (the registry takes

        ' precedence over the cross-thread state routing for that fieldId).

        '

        ' @param {object} node - SG node created on this task thread (e.g. roSGNode "ChannelStore")

        ' @param {string} fieldId - The node field to observe (e.g. "requestStatus")

        ' @param {string} dispatcherId - Dispatcher whose onSourceEvent receives the events

        '

        public sub registerNodeObserver(node as object, fieldId as string, dispatcherId as string)

                ' A fieldId equal to a dispatcher id would shadow that dispatcher's

                ' cross-thread state routing (the registry is checked first). Surface it.

                end if

            #end if

            ' Re-registering the same fieldId onto a different node: drop the stale

            ' observer on the previous node so it does not keep firing after rebind.

            end if

                dispatcherId: dispatcherId,

                node: node

            }

        end sub

        ' ---------------------------------------------------------------------

        ' unregisterNodeObserver - Removes an SG-node field observer registration

        '

        ' @param {object} node - The observed SG node

        ' @param {string} fieldId - The observed field

        '

        public sub unregisterNodeObserver(node as object, fieldId as string)

            end if

        end sub

        ' ---------------------------------------------------------------------

        ' sync - Starts the message loop for cross-thread communication

        '

        ' IMPORTANT: This method creates an infinite loop that handles:

        '   - Intent dispatching from render thread

        '   - External dispatcher registration

        '   - State change notifications

        '   - Async reducer callbacks

        '

        ' This method MUST be the last call in your task function, as it

        ' blocks execution until the framework is destroyed.

        '

        sub sync(waitMs = 0 as integer, onTick = invalid as dynamic)

            ' Initialize tick timer if waitMs > 0

            end if

                    ' Timeout - check if tick interval elapsed

                            ' Tick interval elapsed - call callback

                            ' Reset tick timer

                        end if

                    end if

                                ' taskIntent = Rotor.Utils.deepCopy(intent)

                                end for

                            end if

                            ' Registered SG-node field observer (see registerNodeObserver):

                            ' route the raw event to the owning dispatcher, same contract as

                            ' source objects (onSourceEvent receives the event).

                            end if

                        else

                            end if

                        end if

                    else

                        ' Try identity-based routing

                        if m.sourceObjectRegistry.count() > 0

                            try

                                    ' Apply event filter if provided

                                    end if

                                        end if

                                    end if

                                end if

                            catch e

                                ' Event doesn't support GetSourceIdentity - fall through to broadcast

                            end try

                        end if

                        ' Broadcast to shared source object subscribers

                                    end if

                                        end if

                                    end if

                                end for

                            end for

                        end if

                    end if

                end if

            end while

        end sub

        ' =====================================================================

        ' INTERNAL METHODS

        ' =====================================================================

        ' ---------------------------------------------------------------------

        ' notifySyncStatus - Notifies render thread of sync status

        '

        ' Sends sync status message to render thread via rotorSync field.

        '

        ' @param {string} status - Sync status type (TASK_SYNCING or TASK_SYNCED)

        '

        sub notifySyncStatus(status as string)

                type: Rotor.Const.RouterMsgType.SYNC,

                syncType: status,

                taskNode: m.taskNode

            }

                end for

                    dispatcherIds: dispatcherIds,

                    initialStates: initialStates,

                    tasks: m.config.tasks

                })

            end if

        end sub

        ' ---------------------------------------------------------------------

        ' addObserver - Adds field observer to task thread message port

        '

        ' @param {string} fieldId - Field name to observe

        ' @param {object} node - SceneGraph node to observe

        '

        sub addObserver(fieldId as string, node)

        end sub

        ' ---------------------------------------------------------------------

        ' removeObserver - Removes field observer from node

        '

        ' @param {string} fieldId - Field name to stop observing

        ' @param {object} node - SceneGraph node to unobserve

        '

        sub removeObserver(fieldId as string, node)

        end sub

        ' =====================================================================

        ' CLEANUP

        ' =====================================================================

        ' ---------------------------------------------------------------------

        ' destroy - Cleans up task thread resources

        '

        ' Destroys dispatcher provider and clears global framework helper.

        '

        public sub destroy()

                end if

            end for

                frameworkInstance: invalid

            }

        end sub

    end class

end namespace