Document Data implementation for Arc and subtleties in use
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 9.7k
- Forks
- 565
- PR merge metrics
- No merged PRs in 30d
Description
From conversation on Zulip with @Zarenor and @cmyr, better document the behavior and limitations of `Arc` as used with druid in a type implementing `Data`, to avoid pitfalls like hidden mutability (interior mutability with `RefCell`) which breaks druid's update.
> I just had a look at the implementation of `Data` for `Arc` [...]. It seems the `same`-ness is implemented in terms of pointer equality. As far as I understand, this means if the data behind the smart pointer change, druid will not see it. Yet the [documentation on `Data`](https://linebender.org/druid/data.html) seems to imply that you can just use `Arc` and everything works as expected. But I don't see how that can be true. [...]
> Druid doesn't like internal mutation. The expected pattern would be to use `Arc::make_mut()` to get `&mut T`, and then make sure the argument gets written back to. This will then propagate back up the tree.
> I think I'm also doing it wrong by having an entire collection behind that Arc, whereas I should probably have a collection of trait objects, each single element being individually behind an Arc. That way mutability surfaces per-element. Otherwise the price or rebuilding an entire collection for each modified element sounds high.
> In runebender I do something like `Arc>>` for these sorts of cases.
In short, modify doc to:
- Explain `impl Data for Arc` uses pointer equality to implement `same()`
- Show a good use example with `Arc::make_mut()` and re-assign after change
- Explain the `Vec>` pattern
Contributor guide
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.
Research direction
Start with the Data documentation linked in the issue and inspect its discussion of Arc and same(). Confirm how pointer equality, Arc::make_mut(), reassignment, and the Vec> pattern should be explained. Done means the documentation covers the stated limitations and examples without leaving the hidden-mutability pitfall ambiguous.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 72/100