linebender / linebender/druid

Document Data implementation for Arc and subtleties in use

Open Beginner friendly
#1,758 0 comments 4 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

docs help wanted
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.