clockworklabs / clockworklabs/SpacetimeDB
C#/Unity SDK - Double-buffer client cache indices on the parser thread
@rekhoff is already working on this.
Since Jun 25, 2025.
- Dominant language
- Rust
- Stars
- 25.2k
- Forks
- 1.1k
- Avg merge
- 2d 7h
- Merged PRs (30d)
- 46
Description
Currently, the SDK parsing thread can't fully prepare insert/update/delete information because it can't see the current state of the client cache. For example, the parsing thread may see 2 deletes of a row, but it can't know whether these will actually result in a delete callback being called. This is because the client cache might have 3 copies of the row!
This means that some information about state changes has to be computed on the main thread. This includes building lists of rows that need callbacks, and a lot of index maintenance work.
We could fix this by maintaining a relatively lightweight copy of the client cache on the parsing thread. This wouldn't store copies of rows, only copies of indices. This is thread-safe because we treat rows as immutable.
Benefits of this are:
- Pre-build lists of rows that need callbacks off the main thread
- Prepare operations on indexes off of the main thread. Ideally, for BTreeIndexes this means building a
Dictionary<IndexKey, (HashSet<Row> adds, HashSet<Row> deletes)off of the main thread. - Simplify MultiDictionary logic by getting rid of MultiDictionaryDelta
Drawbacks:
- More memory usage. We don't need to store multiple copies of each row, since rows are immutable in the SDK; but we would need to store a second copy of all indexes and
primary key -> rowmaps.
Alternatives:
A lighter-weight solution would be just pre-building HashSets for BTreeIndexes for insert-only transactions off of the main thread. This speeds up one case that we spend a lot of time on with less complexity.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.