Add some developer docs #349
Conversation
|
See also clockworklabs/SpacetimeDB#2938 |
|
|
||
| `DbConnection` in the generated code inherits from `DbConnectionBase<...>` in the SDK code, which lives in [`src/SpacetimeDBClient.cs`](./src/SpacetimeDBClient.cs). This is a general pattern. Similar inheritance patterns are used for tables and indexes: the generated code defines a class that inherits most of its behavior from a class in the SDK. | ||
|
|
||
| We require that **a DbConnection is only accessed from a single thread**, which should call the `DbConnection.FrameTick()` method frequently. See [threading model](#threading-model), below. |
|
|
||
| The C# SDK, unlike the [Rust SDK](https://github.com/clockworklabs/SpacetimeDB/tree/master/crates/sdk), **assumes a DbConnection is only accessed from a single thread**. This thread is referred to as the "main thread". The "main thread" is: | ||
| - Whichever thread is repeatedly calling `DbConnection.FrameTick()` in a loop. | ||
| It is **only safe to call `FrameTick()` from a single thread**. It is **only safe to access the DbConnection from this thread**. |
There was a problem hiding this comment.
Is this solvable/fixable with a lock?
There was a problem hiding this comment.
Would require locking on all accesses of conn.Db. I don't think there's a nice way to do this without an API break. The type system is just much less expressive RE: sharing.
There was a problem hiding this comment.
Even if you, say, require conn.Db to be accessed from a callback that has a lock on the database, the user can still just store the Db you passed outside the callback. In the end I think the only way to do it would be to have the user manage the lock.
We could think about doing something MVCC-y, where each conn.Db you see is actually immutable, and you're just getting new copies of the Db on changes, but I would be worried about the perf implications there.
There was a problem hiding this comment.
That might allow more work to be done in the background threads, but it would naively involve a lot more allocations since you'd be creating a new copy of the indices each frame. It might work to just have pools of Dictionary<...> lying around that we reuse. Alternatively, we find some sort of haskelly immutable dictionary that can share state between copies.
Thanks Phoebe Co-authored-by: Phoebe Goldman <phoebe@goldman-tribe.org>
Description of Changes
Add some developer docs.
API
Requires SpacetimeDB PRs
Testsuite
SpacetimeDB branch name: master
Testing
N/A