Skip to content

feat(queries): Task fn replaces ForeachChannel #27

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ragoune merged 2 commits into from
Dec 17, 2025
Merged

feat(queries): Task fn replaces ForeachChannel #27

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
22ced65
feat(queries): Task fn replaces ForeachChannel
ragoune Dec 10, 2025
1ddc95f
chore: rename data to result in Query.Task
ragoune Dec 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 33 additions & 16 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,8 @@ for result := range query.Foreach(nil) {
transformData(result.A)
}
```
The Foreach function receives a function to pre-filter the results, and returns an iterator.

DEPRECATED: The Foreach function receives a function to pre-filter the results, and returns an iterator.

For faster performances, you can use concurrency with the function ForeachChannel:
```go
Expand Down Expand Up @@ -143,6 +144,21 @@ func runWorkers(workersNumber int, worker func(int)) {
}
```

The Task function replaces the previous ForeachChannel function: it gives a simpler API with smaller memory footprint, for similar performances.

It is useful for executing code on all queried entities, by dispatching the work across a defined number of workers.
Internally, this function leverages the iterator typically obtained through the Foreach function.

The number of workers should be considered based on the task's complexity:
dispatching has a minmal overhead that might outweigh the benefits if the entity count to worker count ratio is not appropriate.
```go
query := volt.CreateQuery2[transformComponent, meshComponent](world, volt.QueryConfiguration{OptionalComponents: []volt.OptionalComponent{meshComponentId}})

query.Task(4, nil, func(result volt.QueryResult2[transformComponent, meshComponent]) {
transformData(result.A)
})
```

Queries exist for 1 to 8 Components.

You can also get the number of entities, without looping on each:
Expand Down Expand Up @@ -255,21 +271,22 @@ goarch: amd64
pkg: benchmark
cpu: AMD Ryzen 7 5800X 8-Core Processor

| Benchmark | Iterations | ns/op | B/op | Allocs/op |
|---------------------------------|------------|-----------|------------|-----------|
| BenchmarkCreateEntityArche-16 | 171 | 7138387 | 11096954 | 61 |
| BenchmarkIterateArche-16 | 2798 | 429744 | 354 | 4 |
| BenchmarkAddArche-16 | 253 | 4673362 | 122153 | 100000 |
| BenchmarkRemoveArche-16 | 247 | 4840772 | 100000 | 100000 |
| BenchmarkCreateEntityUECS-16 | 27 | 38852089 | 49119503 | 200146 |
| BenchmarkIterateUECS-16 | 4892 | 235333 | 128 | 3 |
| BenchmarkAddUECS-16 | 28 | 38982533 | 4721942 | 100005 |
| BenchmarkRemoveUECS-16 | 30 | 40290316 | 3336712 | 100000 |
| BenchmarkCreateEntityVolt-16 | 63 | 18836136 | 35181458 | 100101 |
| BenchmarkIterateVolt-16 | 3619 | 337764 | 256 | 8 |
| BenchmarkIterateConcurrentlyVolt-16 | 9164 | 121653 | 3324 | 91 |
| BenchmarkAddVolt-16 | 103 | 11379690 | 4313182 | 300000 |
| BenchmarkRemoveVolt-16 | 146 | 7647252 | 400001 | 100000 |
| Benchmark | Iterations | ns/op | B/op | Allocs/op |
|--------------------------------------------------|-------------|-----------|------------|-----------|
| BenchmarkCreateEntityArche-16 | 171 | 7138387 | 11096954 | 61 |
| BenchmarkIterateArche-16 | 2798 | 429744 | 354 | 4 |
| BenchmarkAddArche-16 | 253 | 4673362 | 122153 | 100000 |
| BenchmarkRemoveArche-16 | 247 | 4840772 | 100000 | 100000 |
| BenchmarkCreateEntityUECS-16 | 27 | 38852089 | 49119503 | 200146 |
| BenchmarkIterateUECS-16 | 4892 | 235333 | 128 | 3 |
| BenchmarkAddUECS-16 | 28 | 38982533 | 4721942 | 100005 |
| BenchmarkRemoveUECS-16 | 30 | 40290316 | 3336712 | 100000 |
| BenchmarkCreateEntityVolt-16 | 63 | 18836136 | 35181458 | 100101 |
| BenchmarkIterateVolt-16 | 3619 | 337764 | 256 | 8 |
| (DEPRECATED) BenchmarkIterateConcurrentlyVolt-16 | 9164 | 121653 | 3324 | 91 |
| BenchmarkTaskVolt-16 | 9859 | 119525 | 1847 | 38 |
| BenchmarkAddVolt-16 | 103 | 11379690 | 4313182 | 300000 |
| BenchmarkRemoveVolt-16 | 146 | 7647252 | 400001 | 100000 |

These results show a few things:
- Arche is the fastest tool for writes operations. In our game development though we would rather lean towards fastest read operations, because the games loops will read way more often than write.
Expand Down
21 changes: 21 additions & 0 deletions benchmark/volt_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,27 @@ func BenchmarkIterateConcurrentlyVolt(b *testing.B) {
b.ReportAllocs()
}

func BenchmarkTaskVolt(b *testing.B) {
world := volt.CreateWorld(ENTITIES_COUNT)
volt.RegisterComponent[testTransform](world, &volt.ComponentConfig[testTransform]{})
volt.RegisterComponent[testTag](world, &volt.ComponentConfig[testTag]{})

for i := 0; i < ENTITIES_COUNT; i++ {
id := world.CreateEntity()
volt.AddComponent[testTransform](world, id, testTransform{})
volt.AddComponent[testTag](world, id, testTag{})
}

for b.Loop() {
query := volt.CreateQuery2[testTransform, testTag](world, volt.QueryConfiguration{})
query.Task(WORKERS, nil, func(result volt.QueryResult2[testTransform, testTag]) {
transformData(result.A)
})
}

b.ReportAllocs()
}

func BenchmarkAddVolt(b *testing.B) {
b.StopTimer()

Expand Down
Loading
Loading