feat: graph refactor chapter I by poneciak57 · Pull Request #939 · software-mansion/react-native-audio-api

poneciak57 · 2026-02-05T16:52:01Z

Closes #

Base for many features that can not be implemented with current graph processing structure. This refactor does not change anything. It aims to implement new structure for graph processing which will allow:

assynchronous fast updates
multiple outputs from node
cycles with delay node
performance improvement
it will allow to get rid of all allocations on audio thread
it will allow to utilize fully asynchronous communication between JS and audio threads

This pull requests contains only not integrated implementations and a lot of unit tests

⚠️ Breaking changes ⚠️

Introduced changes

Checklist

Linked relevant issue
Updated relevant documentation
Added/Conducted relevant tests
Performed self-review of the code
Updated Web Audio API coverage
Added support for web
Updated old arch android spec file

…changed

Copilot

Pull request overview

Bro's inteligence needs to be studied

This pull request introduces the foundational infrastructure for a new graph processing system that will enable asynchronous updates, multiple outputs, cycles with delay nodes, and allocation-free audio thread operation. The changes are non-integrated, consisting of new data structures, algorithms, and comprehensive unit tests.

Changes:

Implements new thread-safe graph system with separate HostGraph (main thread) and AudioGraph (audio thread) coordination
Adds allocation-free InputPool for edge storage and custom allocators/disposers
Creates comprehensive test infrastructure with allocation tracking, fuzz testing, and concurrency tests

Reviewed changes

Copilot reviewed 31 out of 31 changed files in this pull request and generated 14 comments.

Show a summary per file

File	Description
AudioGraph.hpp	Implements cache-friendly topological sort and compaction with O(1) extra space
HostGraph.hpp	Main-thread graph mirror with cycle detection via DFS
Graph.hpp	Thread-safe coordinator bridging host/audio graphs via SPSC channel
InputPool.hpp	Free-list pool for allocation-free edge storage during audio processing
FatFunction.hpp	Fixed-size function wrapper avoiding heap allocation
NodeHandle.hpp	Shared handle bridging HostGraph and AudioGraph ownership
HostNode.hpp	RAII base class for host-side audio nodes
Disposer.hpp	Off-thread disposal system for old buffers
AudioNode.h/.cpp	Adds canBeDestructed() method for graph compaction control
Test files	Comprehensive unit, fuzz, and concurrency tests with allocation tracking
Build/CI files	Separate test suite with sanitizer support and Docker environment

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

packages/react-native-audio-api/common/cpp/test/src/graph/GraphTest.cpp

packages/react-native-audio-api/common/cpp/test/src/graph/GraphCycleDebugTest.cpp

packages/react-native-audio-api/common/cpp/test/src/FatFunctionTest.cpp

packages/react-native-audio-api/common/cpp/audioapi/core/utils/graph/HostGraph.hpp

packages/react-native-audio-api/common/cpp/test/src/graph/GraphCycleDebugTest.cpp

packages/react-native-audio-api/common/cpp/audioapi/core/utils/graph/Graph.hpp

packages/react-native-audio-api/common/cpp/test/src/graph/TestGraphUtils.h

packages/react-native-audio-api/common/cpp/test/src/FatFunctionTest.cpp

packages/react-native-audio-api/common/cpp/test/src/graph/SandboxTest.cpp

.github/workflows/graph-tests.yml

michalsek

It feels awkward to write just LGTM under this PR, so here are lyrics for Queens We are the champions. Great job! (And check the copilot comments 🙂)

I've paid my dues
Time after time
I've done my sentence
But committed no crime
And bad mistakes
I've made a few
I've had my share of sand kicked in my face
But I've come through
(We're gonna go on and on and on and on)
We are the champions, my friend
And we'll keep on fighting till the end
We are the champions
We are the champions
No time for losers
Cause we are the champions
Of the world
I've taken my bows
And my curtain calls
You brought me fame and fortune and everything that goes with it
I thank you all
But it's been no bed of roses
No pleasure cruise
I consider it a challenge before the whole human race
And I ain't gonna lose
(We're gonna go on and on and on and on)
We are the champions, my friends
And we'll keep on fighting till the end
We are the champions
We are the champions
No time for losers
Cause we are the champions of the world
We are the champions, my friends
And we'll keep on fighting till the end
We are the champions
We are the champions
No time for losers
Cause we are the champions
Of the world

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…hCycleDebugTest.cpp Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

poneciak57 · 2026-02-24T18:21:53Z

ok there is memory leak possibly due to some time race in tests but seems like a real deal on these actions
https://github.com/software-mansion/react-native-audio-api/actions/runs/22363798273/job/64724228204
https://github.com/software-mansion/react-native-audio-api/actions/runs/22364191757/job/64725634184?pr=939

it needs to be checked, possible cause stale grow pool event in events queue is not properly destructed
possible fix: wrap it in unique_ptr

Edit: Done

…ansion/react-native-audio-api into feat/graph_refactor_1

mdydek · 2026-03-03T12:44:51Z

packages/react-native-audio-api/common/cpp/test/src/FatFunctionTest.cpp

@@ -0,0 +1,226 @@
+


Suggested change

mdydek · 2026-03-03T12:48:39Z

packages/react-native-audio-api/common/cpp/test/src/FatFunctionTest.cpp

+  constexpr size_t dataSize = 64 + sizeof(void*) * 3;
+  constexpr size_t alignment = alignof(std::max_align_t);
+  constexpr size_t expectedSize = (dataSize + alignment - 1) & ~(alignment - 1);


explain more in a code comments why dataSize is like that and expectedSize can be made more readable, we don't need fast bit tricks, since these are only tests, which do not benefit from blazingly fast code

packages/react-native-audio-api/common/cpp/audioapi/core/utils/graph/Disposer.hpp

packages/react-native-audio-api/common/cpp/audioapi/core/utils/graph/Graph.hpp

maciejmakowski2003 · 2026-03-04T12:03:19Z

packages/react-native-audio-api/common/cpp/audioapi/core/utils/graph/README.md

+Graph class is an orhestrator that provides high level API and manages internal structures like `AudioGraph`, `HostGraph`, `SPSC`, `Disposer` and pool capacity.
+
+## HostGraph
+`HostGraph.hpp` contains the `HostGraph` class which is responsible for managing the graph structure and providing low level API for it. It keeps track of nodes, edges, their connections, cycles and other internal metadata. It also provides API for adding, removing and connecting nodes. Each modification returns a `AGEvent` which is a closure that can be executed to apply the same modification on corelated `AudioGraph`. This move allows us to keep `HostGraph` in a state after uptade while sending async event to Audio thread, as we know if events are applied in order, we can be sure that the state of `AudioGraph` in time frame T1 will be the same as `HostGraph` in the same time frame T1.


Suggested change

`HostGraph.hpp` contains the `HostGraph` class which is responsible for managing the graph structure and providing low level API for it. It keeps track of nodes, edges, their connections, cycles and other internal metadata. It also provides API for adding, removing and connecting nodes. Each modification returns a `AGEvent` which is a closure that can be executed to apply the same modification on corelated `AudioGraph`. This move allows us to keep `HostGraph` in a state after uptade while sending async event to Audio thread, as we know if events are applied in order, we can be sure that the state of `AudioGraph` in time frame T1 will be the same as `HostGraph` in the same time frame T1.

`HostGraph.hpp` contains the `HostGraph` class which is responsible for managing the graph structure and providing low level API for it. It keeps track of nodes, edges, their connections, cycles and other internal metadata. It also provides API for adding, removing and connecting nodes. Each modification returns a `AGEvent` which is a closure that can be executed to apply the same modification on corelated `AudioGraph`. This move allows us to keep `HostGraph` in a state after update while sending async event to Audio thread, as we know if events are applied in order, we can be sure that the state of `AudioGraph` in time frame T1 will be the same as `HostGraph` in the same time frame T1.

maciejmakowski2003 · 2026-03-04T12:05:12Z

packages/react-native-audio-api/common/cpp/audioapi/core/utils/graph/README.md

+> So in worst case HostGraph can silent out edge creation if it thinks it would create a cycle, this is very rare case and false negative is acceptable compared to false negative. I don't even know if this is reachable in any realistic scenario, but it is worth to mention.
+
+## AudioGraph
+`AudioGraph.hpp` contains the `AudioGraph` class which is responsible for processing the graph structure on the audio thread. It keeps track of nodes, edges, their inputs and has topological order. It minimazes memory usage, speed of processing and limits memory fragmentation by using `InputPool` to manage edges. It also provides API for processing the graph structure and applying events from `HostGraph`.


Suggested change

`AudioGraph.hpp` contains the `AudioGraph` class which is responsible for processing the graph structure on the audio thread. It keeps track of nodes, edges, their inputs and has topological order. It minimazes memory usage, speed of processing and limits memory fragmentation by using `InputPool` to manage edges. It also provides API for processing the graph structure and applying events from `HostGraph`.

`AudioGraph.hpp` contains the `AudioGraph` class which is responsible for processing the graph structure on the audio thread. It keeps track of nodes, edges, their inputs and has topological order. It minimizes memory usage, speed of processing and limits memory fragmentation by using `InputPool` to manage edges. It also provides API for processing the graph structure and applying events from `HostGraph`.

maciejmakowski2003 · 2026-03-04T12:06:12Z

packages/react-native-audio-api/common/cpp/audioapi/core/utils/graph/README.md

+`InputPool.hpp` contains the `InputPool` class which is responsible for managing the pool of edges. It is designed to be as efficient as possible, so it uses a free list to manage the pool of edges. It also provides API for allocating and deallocating edges. It is designed to be used on the audio thread, so it is not thread safe and should be used within the `AudioGraph` class. Or its events.
+
+## NodeHandle
+`NodeHandle.hpp` contains the `NodeHandle` class which is responsible for managing node index in AudioGraph. Indexes are 32 bit to minimize memory usage and maximize cache efficiency. So it is only to be used in `AGEvent` closures to reference nodes in `AudioGraph` only having a handle to it.


Suggested change

`NodeHandle.hpp` contains the `NodeHandle` class which is responsible for managing node index in AudioGraph. Indexes are 32 bit to minimize memory usage and maximize cache efficiency. So it is only to be used in `AGEvent` closures to reference nodes in `AudioGraph` only having a handle to it.

`NodeHandle.hpp` contains the `NodeHandle` class which is responsible for managing node index in AudioGraph. Indices are 32 bit to minimize memory usage and maximize cache efficiency. So it is only to be used in `AGEvent` closures to reference nodes in `AudioGraph` only having a handle to it.

maciejmakowski2003 · 2026-03-04T12:11:26Z

packages/react-native-audio-api/common/cpp/test/graph_tests_docs.md

+
+
+## Tips and tricks
+As running docker tests takes forevewer it is recommended to relly on CI/CD. Tests without docker does not have ASAN and may not catch memory leaks or address realated issues. So if anny of these issues occur in CI/CD here is how you can run single test with docker to debug it locally:


Suggested change

As running docker tests takes forevewer it is recommended to relly on CI/CD. Tests without docker does not have ASAN and may not catch memory leaks or address realated issues. So if anny of these issues occur in CI/CD here is how you can run single test with docker to debug it locally:

As running docker tests takes forevewer it is recommended to relly on CI/CD. Tests without docker does not have ASAN and may not catch memory leaks or address realated issues. So if any of these issues occur in CI/CD here is how you can run single test with docker to debug it locally:

maciejmakowski2003 · 2026-03-05T11:22:11Z

packages/react-native-audio-api/common/cpp/test/src/graph/SandboxTest.cpp

@@ -0,0 +1,24 @@
+


you can delete it

maciejmakowski2003 · 2026-03-05T12:34:22Z

packages/react-native-audio-api/common/cpp/audioapi/core/utils/graph/Graph.hpp

+  void sendPoolGrowIfNeeded() {
+    auto edges = static_cast<std::uint32_t>(hostGraph.edgeCount());
+    if (edges > poolCapacity_ / 2 || (poolCapacity_ == 0 && edges > 0)) {
+      std::uint32_t newCap = std::max(static_cast<std::uint32_t>(edges * 2), std::uint32_t{64});


let's include that constraint directly in inputPool ctor

maciejmakowski2003 · 2026-03-09T09:59:42Z

packages/react-native-audio-api/common/cpp/audioapi/core/utils/graph/HostGraph.hpp

+    for (Node *n : nodes)
+      delete n;


Suggested change

for (Node *n : nodes)

delete n;

for (Node *n : nodes) {

delete n;

}

maciejmakowski2003 · 2026-03-09T10:02:42Z

packages/react-native-audio-api/common/cpp/audioapi/core/utils/graph/HostGraph.hpp

+  if (start == end)
+    return true;


Suggested change

if (start == end)

return true;

if (start == end) {

return true;

}

maciejmakowski2003 · 2026-03-09T11:14:11Z

packages/react-native-audio-api/common/cpp/test/src/graph/AudioThreadGuard.cpp

+void *operator new(std::size_t size) {
+  audioapi::test::AudioThreadGuard::recordAllocation();
+  void *p = std::malloc(size);
+  if (!p) throw std::bad_alloc();
+  return p;
+}
+
+void *operator new[](std::size_t size) {
+  audioapi::test::AudioThreadGuard::recordAllocation();
+  void *p = std::malloc(size);
+  if (!p) throw std::bad_alloc();
+  return p;
+}
+


double implementation

maciejmakowski2003 · 2026-03-09T11:18:30Z

packages/react-native-audio-api/common/cpp/test/src/graph/MockGraphProcessor.h

+      // Drain events (grow + graph-mutation). May allocate — unguarded.
+      graph_.processEvents();


why it is allowed to allocate here? as I understand it is mock of audio engine render function, so allocations are forbidden.

leftover comment will be fixed

feat: prepared all files

1f8331f

poneciak57 changed the title ~~feat: graph refactor part 1~~ feat: graph refactor chapter I Feb 5, 2026

poneciak57 added 22 commits February 6, 2026 13:32

feat: audio graph impl

96965f7

feat: fat function impl with tests

ee90045

fix: fixed tests

2a15c07

feat: declared api and implemented helpers for testing

ec74d13

feat: implemented DSU

bbba712

feat: implemented graph abstraction

6f38afd

chore: formatting

266678d

chore: removed dsu impl

fef0455

feat: changed host graph to use result

cdfa326

feat: implemented graph wrapper

3ea1481

feat: implemented ptr disposer

5f7a529

feat: implemented proper memory management for audio graph

fa3a7da

fix: fixed issue with ghost nodes in hostgraph

210c57a

feat: added templating to graphs

381706b

feat: implemented solid separate standalone mock

4bbd32c

feat: fixed audio thread allocation issue

18d45d6

feat: added disposer back to events

485fffe

feat: added separate script for running graph tests

5fdb386

fix: fixed tests issue

d703f5d

feat: updated CI to run graph tests only if graph related files have …

015d3ea

…changed

feat: added dockerfile for easier asan on macos

af5ad95

fix: fixed issue with fat function move eq operator

59c6fdf

poneciak57 marked this pull request as ready for review February 24, 2026 10:21

poneciak57 requested review from maciejmakowski2003, mdydek and michalsek as code owners February 24, 2026 10:21

michalsek requested a review from Copilot February 24, 2026 13:19

Copilot started reviewing on behalf of michalsek February 24, 2026 13:19 View session

Copilot AI reviewed Feb 24, 2026

View reviewed changes

michalsek reviewed Feb 24, 2026

View reviewed changes

michalsek approved these changes Feb 24, 2026

View reviewed changes

michalsek requested a review from closetcaiman February 24, 2026 13:55

poneciak57 and others added 3 commits February 24, 2026 19:08

Update .github/workflows/graph-tests.yml

649735e

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update packages/react-native-audio-api/common/cpp/test/src/graph/Grap…

a70a8f6

…hCycleDebugTest.cpp Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update packages/react-native-audio-api/common/cpp/test/src/graph/Grap…

ec104b4

…hCycleDebugTest.cpp Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

poneciak57 added 4 commits February 25, 2026 13:02

fix: fixed memory leak and comments from copilot

8167770

Merge branch 'feat/graph_refactor_1' of https://github.com/software-m…

0e8b904

…ansion/react-native-audio-api into feat/graph_refactor_1

fix: fixed fat function to work properly with mutable closures

88156eb

docs: graph overall docs with essential info

483b985

poneciak57 mentioned this pull request Mar 3, 2026

Refactor/communication between audio and js thread #942

Merged

7 tasks

mdydek reviewed Mar 9, 2026

View reviewed changes

maciejmakowski2003 requested changes Mar 9, 2026

View reviewed changes

	`NodeHandle.hpp` contains the `NodeHandle` class which is responsible for managing node index in AudioGraph. Indexes are 32 bit to minimize memory usage and maximize cache efficiency. So it is only to be used in `AGEvent` closures to reference nodes in `AudioGraph` only having a handle to it.
	`NodeHandle.hpp` contains the `NodeHandle` class which is responsible for managing node index in AudioGraph. Indices are 32 bit to minimize memory usage and maximize cache efficiency. So it is only to be used in `AGEvent` closures to reference nodes in `AudioGraph` only having a handle to it.



		## Tips and tricks
		As running docker tests takes forevewer it is recommended to relly on CI/CD. Tests without docker does not have ASAN and may not catch memory leaks or address realated issues. So if anny of these issues occur in CI/CD here is how you can run single test with docker to debug it locally:

		// Drain events (grow + graph-mutation). May allocate — unguarded.
		graph_.processEvents();

Uh oh!

Conversation

poneciak57 commented Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ Breaking changes ⚠️

Introduced changes

Checklist

Uh oh!

Copilot AI left a comment • edited by poneciak57 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

michalsek left a comment

Choose a reason for hiding this comment

Uh oh!

poneciak57 commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

poneciak57 commented Feb 5, 2026 •

edited

Loading

Copilot AI left a comment •

edited by poneciak57

Loading

poneciak57 commented Feb 24, 2026 •

edited

Loading