River_pod: Improve documentation for autoDispose

[venkatd]

Describe what scenario you think is uncovered by the existing examples/articles

The autoDispose section of the article says the following:

To tell Riverpod to destroy the state of a provider when it is no-longer used, simply append .autoDispose to your provider:

I was troubleshooting an app bug related to auto-dispose. When a user was logging out, some of the state for the logged in user wasn't getting destroyed.

It turned out that another provider was depending on it using ref.watch which was preventing the state from being destroyed.

It was unclear to me what "no-longer used means". I think clarifying how riverpod decides what is still in use could help. Maybe with some examples of gotchas.

Describe why existing examples/articles do not cover this case
I think the examples do cover autoDispose, but because there are some gotchas and details on provider lifecycle to be aware of.

Additional context

I would like to confirm the following is the case:

• Something is used if it's being referenced by a widget with "useProvider" OR another provider is in use with read or watch
• If something is disposable, dispose will be called on it. (Would be good to in understand what cases river_pod will dispose something for you without manually calling dispose
• ref.onDispose is additional cleanup to whatever river_pod does. (It doesn't override river_pod dispose)

The troubleshooting steps I wish I had known when autoDispose isn't triggering onDispose

• Check that the provider isn't being referenced in any widgets
• Check that other active providers aren't referencing it

Another idea would be to list all dependencies (widgets+providers) that a provider currently depends on in the DevTools inspector so we can easily see why something is still alive when it should have been disposed.

I can help out with documenting this once my understanding of autoDispose improves.

[rrousselGit]

Agreed

I don't think documentation can help much here. What we are looking is for devtools instead.

A devtool is planned and is my next step after making a few more examples.
It would include this scenario.

But in the short term, the 0.7.0 version will have some improvements about common mistakes around ref.watch
You can see the changelog/doc for this

[venkatd]

Ok awesome! Feel free to mark this as closed then.

The main use cases for me are:

• What depends on provider A? (useful for knowing what is preventing autoDispose from being called, also includes Widgets in the widget tree)
• What does A depend on? (useful for knowing what will rebuild if A changes)

[rrousselGit]

I will keep this open as the devtool isn't technically here yet and the change made doesn't prevent all mistakes.

[venkatd]

Related to this in the meantime would be useful to have a helper like
dependsOn(provider) and dependenciesOf(provider) (don't know the exact naming) so I can print them out while debugging. Does something like this exist in the API? One of my most common debugging scenarios is finding out why something isn't autoDisposed.

[rrousselGit]

You can do that. It's just not obvious

final provider = Provider(...);

ProviderContainer container = ProviderScope.containerOf(context);

container.debug*

final element = container.readProviderElement(provider);
print(element.dependents);

[dgaedcke]

Agreed!! I love Riverpod and one improvement I'd like to see in the documentation is clarity on HOW LONG a provider will live, WITHOUT an active listener, before it will self-dispose / garbage-collect.

I'm probably inventing some bad practices because I don't understand this fully ...
https://stackoverflow.com/questions/64830479/flutter-riverpod-design-pattern-inhibit-garbage-collection