Document Data implementation for Arc and subtleties in use

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 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<Vec<Arc<Item>>> 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<Arc<Item>> pattern