Listener

[busslina]

Hi Greg,

Firstly, can you explain why use.asListener() is needed and how it works?

Declares the associated capsule as a non-idempotent listener.

Instead, create a non-idempotent capsule (a fancy way to say a capsule that registers a side effect) and read it once to ensure it has been initialized and is listening.

Do I need to use it on a capsule that do other stuff?
Or only in a capsule that does only the listening?

My desired outcome is to listen capsuleA (factory) from capsuleB (factory) and then mutate capsuleB state.

So I think I have to create a listenerA and use it on CapsuleB, but there I don't know how to detect what factory item triggered the rebuild

[busslina]

Also, should I do the listening inside callonce?

[busslina]

Also, should I initialize the listener at top level (just after create the CapsuleContainer)?

What if I'm in Flutter where I don't have access to the CapsuleContainer? Maybe calling it in a top level widget initState?

[busslina]

Also seems that we have no CapsuleHandle inside SideEffectRegistrar so we cannot access to other capsules (via call).

[busslina]

I removed some commentaries due to I think I understand now better the whole picture

[GregoryConrad]

I'm going to try to answer all of your questions/comments here:

Firstly, can you explain why use.asListener() is needed and how it works?

Here's why it is needed. Take the following:

int xCapsule(CapsuleHandle use) => /* impl hidden */;
void xLoggerCapsule(CapsuleHandle use) => print(use(xCapsule));

If we read xLoggerCapsule from the container once (so the container knows of its existence), we may then expect for it to log all future values of xCapsule. Here's the catch: it won't. As soon as xCapsule changes, the container will recognize that its only dependents have no "demand" (i.e., nothing downstream registers a side effect), and will garbage collect the xLoggerCapsule without it ever getting executed again.

This garbage collection optimization is exactly what:

1. Allows ReArch to be used for demand-driven incremental computation applications
2. Prevents relying on "AutoDispose" and similar such things to prevent leaks in the container
3. Allows for capsule.map to not cause leaks, as all .map() does is make a new and cheap capsule which we don't want to leak.

As logging, and listening in general, is actually considered a side effect (as they interact with the outside world), use.asListener() was introduced to declare a capsule as having some side effect that does not necessarily go through the SideEffectRegistrar. As far as how use.asListener() is implemented--it is simply a no-op that just calls register with no substantial information so a container knows that the capsule registers a side effect. (It's really just a declarative flag saying "I interact with the outside world in a way that doesn't involve you, so please disable any clever optimizations that you may otherwise employ")

Do I need to use it on a capsule that do other stuff?
Or only in a capsule that does only the listening?

use.asListener() should be used whenever a capsule must get all updates from any dependencies (such as to log them or otherwise listen to changes).

My desired outcome is to listen capsuleA (factory) from capsuleB (factory) and then mutate capsuleB state.

That just sounds like you should instead rely on ReArch's reactivity via:

int Function(int) aFactory(CapsuleHandle use) => /* impl hidden */;
int Function(int) bFactory(CapsuleHandle use) {
  final a = use(aFactory); // bFactory will be rebuilt with a new "a" whenever aFactory rebuilds
  return (i) {
    return a(i) * 2;
  }
}

Also, should I do the listening inside callonce?
Also, should I initialize the listener at top level (just after create the CapsuleContainer)?
What if I'm in Flutter where I don't have access to the CapsuleContainer? Maybe calling it in a top level widget initState?

To initialize a listener/capsule with some side effect, you only need to read it once from the container at a time of your choosing. This is, however, often when a container is first created.

In Dart only, just call container.read(myListener);

In Flutter, you can do something similar, but it'd be better to do something like:

@rearchWidget
Widget initListeners(WidgetHandle use, {required Widget child}) {
  use.callonce(() {
    use(myListener1);
    use(myListener2);
  });
  return child;
}

(I'm too lazy to write out a full widget with all that boilerplate, so just expand the rearchWidget above into your own RearchConsumer)

[GregoryConrad]

Oh, and then put the InitListeners widget directly below your RearchBootstrapper in the widget tree (above any MaterialApp)

[busslina]

Regarding to use.asListener.

Does it means that a proxyCapsule: a capsule that only use and return another sourceCapsule will break the logic?
With logic I mean having a Widget that uses the sourceCapsule will allways rebuild when the capsule rebuilds... but if the Widget uses the proxyCapsule instead it won't ever rebuild.

EDITED I:
okay, I think I understood. It won't break the logic. use.asListener we can say it provides static listening? A listening way that you call once and stays forever alive (at least until container dispose).
If I only want to listen while a Widget is active I can just use the desired target capsule inside the Widget.build()

EDITED II:
Will make sense to stop listening in some way? Disposing an indivual capsule?

[GregoryConrad]

Can you please give a full example of what you’re doing? Having difficulty following exactly But in short if you have a “proxy” capsule that uses some data from a source capsule and returns that data directly, anything dependent on that proxy capsule will rebuild (and then emit new data) whenever the source has new data.

[busslina]

My bad.. Forget about it ;)

[GregoryConrad]

Just saw your edits!

okay, I think I understood. It won't break the logic. use.asListener we can say it provides static listening? A listening way that you call once and stays forever alive (at least until container dispose).
If I only want to listen while a Widget is active I can just use the desired target capsule inside the Widget.build()

that’s all correct!

Will make sense to stop listening in some way? Disposing an indivual capsule?

that’s what CapsuleContainer.listen() is for!

[busslina]

Cool !!