19806426946

Committed 30 Nov 2025 11:23PM UTC coverage: 86.187% (+0.007%) from 86.18%

Build # 19806426946

Build Type

push

github

Committed by

web-flow

Commit Message

Feat/dispatcher shortcuts (#9)

* feat(dispatcher): add widget dispatcher shortcuts for event handling

* feat(notice): add NOTICE file with third-party assets and libraries

* fix(dispatcher): update asyncReducerCallbackId to dispatcherId for correct message handling

* refactor(dispatcher): remove  addListenerTo method from widget (due to missing destroy)

* cleanup(spec): remove spec for addListenerTo

* update README

Coverage Stats

2 of 4 new or added lines in 2 files covered. (50.0%)

1772 of 2056 relevant lines covered (86.19%)

1.17 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

70.59

/src/source/RotorFrameworkTask.bs

' =========================================================================
' ▗▄▄▖  ▗▄▖▗▄▄▄▖▗▄▖ ▗▄▄▖     ▗▄▄▄▖▗▄▄▖  ▗▄▖ ▗▖  ▗▖▗▄▄▄▖▗▖ ▗▖ ▗▄▖ ▗▄▄▖ ▗▖ ▗▖
' ▐▌ ▐▌▐▌ ▐▌ █ ▐▌ ▐▌▐▌ ▐▌    ▐▌   ▐▌ ▐▌▐▌ ▐▌▐▛▚▞▜▌▐▌   ▐▌ ▐▌▐▌ ▐▌▐▌ ▐▌▐▌▗▞▘
' ▐▛▀▚▖▐▌ ▐▌ █ ▐▌ ▐▌▐▛▀▚▖    ▐▛▀▀▘▐▛▀▚▖▐▛▀▜▌▐▌  ▐▌▐▛▀▀▘▐▌ ▐▌▐▌ ▐▌▐▛▀▚▖▐▛▚▖
' ▐▌ ▐▌▝▚▄▞▘ █ ▝▚▄▞▘▐▌ ▐▌    ▐▌   ▐▌ ▐▌▐▌ ▐▌▐▌  ▐▌▐▙▄▄▖▐▙█▟▌▝▚▄▞▘▐▌ ▐▌▐▌ ▐▌
' Rotor Framework™
' Version 0.3.7
' © 2025 Balázs Molnár — MIT License
' =========================================================================

' constants
import "engine/Constants.bs"

' engine
import "engine/providers/DispatcherProvider.bs"
import "engine/providers/Dispatcher.bs"

' base classes
import "base/DispatcherCreator.bs"
import "base/DispatcherExternal.bs"
import "base/BaseReducer.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.3.7"

        config = {
            tasks: invalid, ' optional
            debug: {
            }
        }

        threadType = Rotor.Const.ThreadType.TASK

        keepAlive = true

        ' helper vars
        taskNode as object
        dispatcherProvider as object
        port as object

        ' ---------------------------------------------------------------------
        ' 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)

            Rotor.Utils.deepExtendAA(m.config, config)

            globalScope = GetGlobalAA()
            globalScope.rotor_framework_helper = { ' this give to dispatcher instance the possibility to self-register
                threadType: m.threadType,
                frameworkInstance: m
            }
            m.taskNode = globalScope.top

            m.dispatcherProvider = new Rotor.DispatcherProvider(m.threadType)

            m.taskNode.addField("rotorSync", "assocarray", true)
            m.port = CreateObject("roMessagePort")
            m.taskNode.observeFieldScoped("rotorSync", m.port)

        end sub

        ' =====================================================================
        ' PUBLIC API
        ' =====================================================================

        ' ---------------------------------------------------------------------
        ' getDispatcher - Gets dispatcher facade by ID
        '
        ' @param {string} dispatcherId - Dispatcher identifier
        ' @returns {object} Dispatcher facade instance
        '
        public function getDispatcher(dispatcherId as string) as object
            return m.dispatcherProvider.getFacade(dispatcherId, GetGlobalAA())
        end function

        ' ---------------------------------------------------------------------
        ' 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()
            m.notifySyncStatus(Rotor.Const.ThreadSyncType.TASK_SYNCING)

            keepAlive = true

            while true and keepAlive = true
                msg = wait(0, m.port)
                if msg <> invalid
                    msgType = type(msg)
                    if msgType = "roSGNodeEvent"
                        fieldId = msg.getField()

                        if fieldId = "rotorSync"

                            sync = msg.getData() ' @type:AA

                            if sync.type = Rotor.Const.ThreadSyncType.DISPATCH


                                dispatcherId = sync.payload.dispatcherId
                                intent = sync.payload.intent
                                dispatcherInstance = m.dispatcherProvider.stack.LookupCI(dispatcherId)

                                ' taskIntent = Rotor.Utils.deepCopy(intent)
                                dispatcherInstance.dispatch(intent)

                            else if sync.type = Rotor.Const.ThreadSyncType.REGISTER_EXTERNAL_DISPATCHER

                                for each item in sync.externalDispatcherList
                                    m.dispatcherProvider.registerExternalDispatchers(item.dispatcherId, item.externalTaskNode)
                                end for

                                m.notifySyncStatus(Rotor.Const.ThreadSyncType.TASK_SYNCED)

                            else if sync.type = Rotor.Const.ThreadSyncType.DESTROY

                                keepAlive = false

                            end if
                        else

                            data = msg.getData()
                            extraInfo = msg.GetInfo() ' Info AA passed during observeFieldScoped

                            if extraInfo?.dispatcherId <> invalid and m.dispatcherProvider.get(extraInfo?.dispatcherId) <> invalid
                                ' Catch by dispatcherId
                                m.dispatcherProvider.get(extraInfo?.dispatcherId).asyncReducerCallback(msg)
                            else
                                dispatcherId = fieldId
                                dispatcherInstance = m.dispatcherProvider.get(dispatcherId)
                                dispatcherInstance.notifyListeners(data)
                            end if

                        end if
                    end if
                end if
            end while
            m.destroy()
        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)

            payload = {
                type: status,
                taskNode: m.taskNode
            }

            if status = Rotor.Const.ThreadSyncType.TASK_SYNCING
                payload.append({
                    dispatcherIds: m.dispatcherProvider.stack.Keys(),
                    tasks: m.config.tasks
                })
            end if

            m.taskNode.rootNode.setField("rotorSync", payload)

        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)
            node.observeFieldScoped(fieldId, m.port)
        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)
            node.unobserveFieldScoped(fieldId)
        end sub

        ' =====================================================================
        ' CLEANUP
        ' =====================================================================

        ' ---------------------------------------------------------------------
        ' destroy - Cleans up task thread resources
        '
        ' Destroys dispatcher provider and clears global framework helper.
        '
        public sub destroy()
            m.dispatcherProvider.destroy()

            globalScope = GetGlobalAA()
            globalScope.rotor_framework_helper = {
                frameworkInstance: invalid
            }

            m.taskNode.rootNode = invalid
            m.taskNode = invalid
        end sub

    end class

end namespace





1	' =========================================================================
2	' ▗▄▄▖ ▗▄▖▗▄▄▄▖▗▄▖ ▗▄▄▖ ▗▄▄▄▖▗▄▄▖ ▗▄▖ ▗▖ ▗▖▗▄▄▄▖▗▖ ▗▖ ▗▄▖ ▗▄▄▖ ▗▖ ▗▖
3	' ▐▌ ▐▌▐▌ ▐▌ █ ▐▌ ▐▌▐▌ ▐▌ ▐▌ ▐▌ ▐▌▐▌ ▐▌▐▛▚▞▜▌▐▌ ▐▌ ▐▌▐▌ ▐▌▐▌ ▐▌▐▌▗▞▘
4	' ▐▛▀▚▖▐▌ ▐▌ █ ▐▌ ▐▌▐▛▀▚▖ ▐▛▀▀▘▐▛▀▚▖▐▛▀▜▌▐▌ ▐▌▐▛▀▀▘▐▌ ▐▌▐▌ ▐▌▐▛▀▚▖▐▛▚▖
5	' ▐▌ ▐▌▝▚▄▞▘ █ ▝▚▄▞▘▐▌ ▐▌ ▐▌ ▐▌ ▐▌▐▌ ▐▌▐▌ ▐▌▐▙▄▄▖▐▙█▟▌▝▚▄▞▘▐▌ ▐▌▐▌ ▐▌
6	' Rotor Framework™
7	' Version 0.3.7
8	' © 2025 Balázs Molnár — MIT License
9	' =========================================================================
10
11	' constants
12	import "engine/Constants.bs"
13
14	' engine
15	import "engine/providers/DispatcherProvider.bs"
16	import "engine/providers/Dispatcher.bs"
17
18	' base classes
19	import "base/DispatcherCreator.bs"
20	import "base/DispatcherExternal.bs"
21	import "base/BaseReducer.bs"
22	import "base/BaseModel.bs"
23	import "base/BaseStack.bs"
24
25	' utils
26	import "utils/GeneralUtils.bs"
27	import "utils/NodeUtils.bs"
28	import "utils/ArrayUtils.bs"
29
30	namespace Rotor
31	' =====================================================================
32	' FrameworkTask - Task thread version of Rotor Framework for MVI
33	'
34	' Task thread version of the Rotor Framework that enables cross-thread MVI
35	' (Model-View-Intent) architecture. This class manages state and dispatchers
36	' on a separate task thread, allowing heavy computations and state management
37	' to run off the render thread for better performance.
38	'
39	' Configuration:
40	' - tasks (array, optional): List of additional task node names to synchronize with.
41	' Allows multiple task threads to communicate and share
42	' dispatchers across different threads.
43	'
44	' USAGE NOTES:
45	' The FrameworkTask must be instantiated in the task's init() function and the sync()
46	' method MUST be called at the end of your task function to establish the message loop.
47	'
48	' IMPORTANT: The sync() method creates an infinite loop that handles cross-thread
49	' communication and dispatcher synchronization. This call should be the LAST statement
50	' in your task function, after all dispatcher initialization.
51	'
52	' Example:
53	' File: MyTask.task.bs
54	' import "pkg:/source/RotorFrameworkTask.bs"
55	' import "pkg:/source/MyDispatcher.bs"
56	'
57	' sub init()
58	' m.top.functionName = "task"
59	' m.appFw = new Rotor.FrameworkTask({
60	' tasks: ["AnotherTask"]
61	' })
62	' end sub
63	'
64	' sub task()
65	' m.fooDispatcher = createFooDispatcher()
66	' m.barDispatcher = createBarDispatcher()
67	' m.appFw.sync()
68	' end sub
69	' =====================================================================
70	class FrameworkTask
71
72	name = "Rotor Framework"
73	version = "0.3.7"
74
75	config = {
76	tasks: invalid, ' optional
77	debug: {
78	}
79	}
80
81	threadType = Rotor.Const.ThreadType.TASK
82
83	keepAlive = true
84
85	' helper vars
86	taskNode as object
87	dispatcherProvider as object
88	port as object
89
90	' ---------------------------------------------------------------------
91	' new - Initializes the FrameworkTask instance
92	'
93	' Sets up the task thread dispatcher provider, message port, and
94	' global framework helper for cross-thread communication.
95	'
96	' @param {object} config - Configuration object (see class documentation)
97	'
98	sub new(config = {} as object)
99
100	Rotor.Utils.deepExtendAA(m.config, config)	1✔
101
102	globalScope = GetGlobalAA()	1✔
103	globalScope.rotor_framework_helper = { ' this give to dispatcher instance the possibility to self-register	1✔
104	threadType: m.threadType,
105	frameworkInstance: m
106	}
107	m.taskNode = globalScope.top	1✔
108
109	m.dispatcherProvider = new Rotor.DispatcherProvider(m.threadType)	1✔
110
111	m.taskNode.addField("rotorSync", "assocarray", true)	1✔
112	m.port = CreateObject("roMessagePort")	1✔
113	m.taskNode.observeFieldScoped("rotorSync", m.port)	1✔
114
115	end sub
116
117	' =====================================================================
118	' PUBLIC API
119	' =====================================================================
120
121	' ---------------------------------------------------------------------
122	' getDispatcher - Gets dispatcher facade by ID
123	'
124	' @param {string} dispatcherId - Dispatcher identifier
125	' @returns {object} Dispatcher facade instance
126	'
127	public function getDispatcher(dispatcherId as string) as object
128	return m.dispatcherProvider.getFacade(dispatcherId, GetGlobalAA())	×
129	end function
130
131	' ---------------------------------------------------------------------
132	' sync - Starts the message loop for cross-thread communication
133	'
134	' IMPORTANT: This method creates an infinite loop that handles:
135	' - Intent dispatching from render thread
136	' - External dispatcher registration
137	' - State change notifications
138	' - Async reducer callbacks
139	'
140	' This method MUST be the last call in your task function, as it
141	' blocks execution until the framework is destroyed.
142	'
143	sub sync()
144	m.notifySyncStatus(Rotor.Const.ThreadSyncType.TASK_SYNCING)	1✔
145
146	keepAlive = true	1✔
147
148	while true and keepAlive = true	1✔
149	msg = wait(0, m.port)	1✔
150	if msg <> invalid	3✔
151	msgType = type(msg)	1✔
152	if msgType = "roSGNodeEvent"	3✔
153	fieldId = msg.getField()	1✔
154
155	if fieldId = "rotorSync"	3✔
156
157	sync = msg.getData() ' @type:AA	1✔
158
159	if sync.type = Rotor.Const.ThreadSyncType.DISPATCH	2✔
160
161
162	dispatcherId = sync.payload.dispatcherId	1✔
163	intent = sync.payload.intent	1✔
164	dispatcherInstance = m.dispatcherProvider.stack.LookupCI(dispatcherId)	1✔
165
166	' taskIntent = Rotor.Utils.deepCopy(intent)
167	dispatcherInstance.dispatch(intent)	1✔
168
169	else if sync.type = Rotor.Const.ThreadSyncType.REGISTER_EXTERNAL_DISPATCHER	2✔
170
171	for each item in sync.externalDispatcherList	×
172	m.dispatcherProvider.registerExternalDispatchers(item.dispatcherId, item.externalTaskNode)	×
173	end for
174
175	m.notifySyncStatus(Rotor.Const.ThreadSyncType.TASK_SYNCED)	×
176
177	else if sync.type = Rotor.Const.ThreadSyncType.DESTROY	3✔
178
179	keepAlive = false	1✔
180
181	end if
182	else
183		×
184	data = msg.getData()	×
185	extraInfo = msg.GetInfo() ' Info AA passed during observeFieldScoped	×
186
NEW 187	if extraInfo?.dispatcherId <> invalid and m.dispatcherProvider.get(extraInfo?.dispatcherId) <> invalid	×
188	' Catch by dispatcherId
NEW 189	m.dispatcherProvider.get(extraInfo?.dispatcherId).asyncReducerCallback(msg)	×
190	else	×
191	dispatcherId = fieldId	×
192	dispatcherInstance = m.dispatcherProvider.get(dispatcherId)	×
193	dispatcherInstance.notifyListeners(data)	×
194	end if
195
196	end if
197	end if
198	end if
199	end while
200	m.destroy()	1✔
201	end sub
202
203	' =====================================================================
204	' INTERNAL METHODS
205	' =====================================================================
206
207	' ---------------------------------------------------------------------
208	' notifySyncStatus - Notifies render thread of sync status
209	'
210	' Sends sync status message to render thread via rotorSync field.
211	'
212	' @param {string} status - Sync status type (TASK_SYNCING or TASK_SYNCED)
213	'
214	sub notifySyncStatus(status as string)
215
216	payload = {	1✔
217	type: status,
218	taskNode: m.taskNode
219	}
220
221	if status = Rotor.Const.ThreadSyncType.TASK_SYNCING	3✔
222	payload.append({	1✔
223	dispatcherIds: m.dispatcherProvider.stack.Keys(),
224	tasks: m.config.tasks
225	})
226	end if
227
228	m.taskNode.rootNode.setField("rotorSync", payload)	1✔
229
230	end sub
231
232	' ---------------------------------------------------------------------
233	' addObserver - Adds field observer to task thread message port
234	'
235	' @param {string} fieldId - Field name to observe
236	' @param {object} node - SceneGraph node to observe
237	'
238	sub addObserver(fieldId as string, node)
239	node.observeFieldScoped(fieldId, m.port)	×
240	end sub
241
242	' ---------------------------------------------------------------------
243	' removeObserver - Removes field observer from node
244	'
245	' @param {string} fieldId - Field name to stop observing
246	' @param {object} node - SceneGraph node to unobserve
247	'
248	sub removeObserver(fieldId as string, node)
249	node.unobserveFieldScoped(fieldId)	×
250	end sub
251
252	' =====================================================================
253	' CLEANUP
254	' =====================================================================
255
256	' ---------------------------------------------------------------------
257	' destroy - Cleans up task thread resources
258	'
259	' Destroys dispatcher provider and clears global framework helper.
260	'
261	public sub destroy()
262	m.dispatcherProvider.destroy()	1✔
263
264	globalScope = GetGlobalAA()	1✔
265	globalScope.rotor_framework_helper = {	1✔
266	frameworkInstance: invalid
267	}
268
269	m.taskNode.rootNode = invalid	1✔
270	m.taskNode = invalid	1✔
271	end sub
272
273	end class
274
275	end namespace
276
277
278
279

mobalazs / rotor-framework / 19806426946

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous