Rust client SDK consistent state views for callbacks #16
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This requires deriving `Debug` for tables and generated types. In the future, we should be careful that all spacetime types can derive `Debug`.
Prior to this commit, callbacks in the Rust client SDK shared access to the global ClientCache while running asynchronously. This meant that a long-running or delayed callback could observe the ClientCache in a state later than the one that caused the callback's invocation, and had no way to access the specific state for which it was invoked. With this commit, each `Invoke` message to the callback worker includes an `Arc<ClientCache>` snapshot of the DB state when that callback was invoked. The callback worker stores that state in a `thread_local`, and methods that inspect tables (e.g. `TableType::iter`) read the state out of the `thread_local` when it is present. This allows callbacks to observe exactly the state which caused their invocation, never a later state, while maintaining the C#-like API where `ClientCache` access is based on free functions or static trait methods.
Centril
reviewed
Jun 26, 2023
Contributor
Centril
left a comment
Centril
left a comment
There was a problem hiding this comment.
Will review more tomorrow :)
Centril
reviewed
Jun 27, 2023
- Type alias `ClientCacheView = Arc<ClientCache>` makes shared views into a particular `ClientCache` state more clear. - Type alias `SharedCell<T> = Arc<Mutex<T>>` makes thread-safe shared mutable places more clear. - CLI generate helper functions `iter_reducer_items` and `iter_table_items` deduplicate loops and reduce rightward drift. - Assorted doc comments.
Centril
reviewed
Jun 29, 2023
Comment on lines
31
to
45
| /// The most recent state of the `ClientCache`, kept in a shared cell | ||
| /// so that the `receiver_loop` can update it, and non-callback table accesses | ||
| /// can observe it via `global_connection::current_or_global_state`. | ||
| /// | ||
| /// If you expand these type aliases, you get `Arc<Mutex<Arc<ClientCache>>>`, | ||
| /// which looks somewhat strange. The type aliases are intended to make clear | ||
| /// the purpose of the two layers of refcounting: | ||
| /// | ||
| /// The outer layer, around the `Mutex`, allows for a shared mutable cell | ||
| /// by which multiple concurrent workers can communicate the most recent state. | ||
| /// | ||
| /// The inner layer, around the `ClientCache`, allows those workers to | ||
| /// cheaply extract a reference to the `ClientCache` | ||
| /// without holding a lock for the lifetime of that reference, | ||
| /// and without changes to the state invalidating the reference. |
Contributor
There was a problem hiding this comment.
This is excellent! It aids understanding by a lot! Perhaps the word "snapshot" could be added in the last paragraph, if it feels natural?
| /// | ||
| /// The existing `ClientCacheView` in `client_cache` is not mutated, | ||
| /// so handles on it held in other places (e.g. by callback workers) | ||
| /// remain valid. |
Contributor
There was a problem hiding this comment.
Maybe add "That is, these workers have their own snapshots."
Centril
approved these changes
Jun 29, 2023
Contributor
Centril
left a comment
Centril
left a comment
There was a problem hiding this comment.
This looks great! With the last changes, things were easier to understand.
cloutiertyler
pushed a commit
that referenced
this pull request
Aug 1, 2023
Prior to this commit, callbacks in the Rust client SDK shared access to the global ClientCache while running asynchronously. This meant that a long-running or delayed callback could observe the ClientCache in a state later than the one that caused the callback's invocation, and had no way to access the specific state for which it was invoked. With this commit, each `Invoke` message to the callback worker includes an `Arc<ClientCache>` snapshot of the DB state when that callback was invoked. The callback worker stores that state in a `thread_local`, and methods that inspect tables (e.g. `TableType::iter`) read the state out of the `thread_local` when it is present. This allows callbacks to observe exactly the state which caused their invocation, never a later state, while maintaining the C#-like API where `ClientCache` access is based on free functions or static trait methods. --------- Co-authored-by: John Detter <4099508+jdetter@users.noreply.github.com>
cloutiertyler
pushed a commit
that referenced
this pull request
Aug 1, 2023
Prior to this commit, callbacks in the Rust client SDK shared access to the global ClientCache while running asynchronously. This meant that a long-running or delayed callback could observe the ClientCache in a state later than the one that caused the callback's invocation, and had no way to access the specific state for which it was invoked. With this commit, each `Invoke` message to the callback worker includes an `Arc<ClientCache>` snapshot of the DB state when that callback was invoked. The callback worker stores that state in a `thread_local`, and methods that inspect tables (e.g. `TableType::iter`) read the state out of the `thread_local` when it is present. This allows callbacks to observe exactly the state which caused their invocation, never a later state, while maintaining the C#-like API where `ClientCache` access is based on free functions or static trait methods. --------- Co-authored-by: John Detter <4099508+jdetter@users.noreply.github.com>
bfops
pushed a commit
that referenced
this pull request
Jul 16, 2025
Merged the player and logged_out_player tables into only a player table, to match the way it is used in the tutorial documentation. Slight changes to how logged_out_player was being referenced was required due to the tables having different architecture.
bfops
pushed a commit
that referenced
this pull request
Jul 17, 2025
* Copied changes from BitCraft * Applied state diff changes * State diffs complete * Compilation fix * Fix build issues --------- Co-authored-by: John Detter <no-reply@boppygames.gg>
bfops
pushed a commit
that referenced
this pull request
Aug 7, 2025
* Copied changes from BitCraft * Applied state diff changes * State diffs complete * Compilation fix * Fix build issues --------- Co-authored-by: John Detter <no-reply@boppygames.gg>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description of Changes
Prior to this commit, callbacks in the Rust client SDK shared access to the global ClientCache while running asynchronously. This meant that a long-running or delayed callback could observe the ClientCache in a state later than the one that caused the callback's invocation, and had no way to access the specific state for which it was invoked.
With this commit, each
Invokemessage to the callback worker includes anArc<ClientCache>snapshot of the DB state when that callback was invoked. The callback worker stores that state in athread_local, and methods that inspecttables (e.g.
TableType::iter) read the state out of thethread_localwhen it is present. This allows callbacks to observe exactly the state which caused their invocation, never a later state, while maintaining the C#-like API whereClientCacheaccess is based on free functions or static trait methods.API
If the API is breaking, please state below what will break