Allow "destroying" the environment to properly shutdown services

[t0bst4r]

I'd like to use the environment as some kind of "dependency injection" tool to pass custom services into my behaviors.
Some services require async initialization and async disposal.

As environment.set already suggests, I can register my own services. Additionally environment.load already considers async initialization and waits for it to be finished.
The corresponding interface Environmental.Service already includes an optional asyncDispose function, which is described as follows:

        /**
         * Asynchronous destruction.  Invoked by the environment when it is destroyed.
         */
        [Symbol.asyncDispose]?: () => Promise<any>;

Anyway there seems to be no way to "destroy" the environment. Additionally I couldn't find any place in matter.js where this is called for #services.
Even when using process signals to stop the app, asyncDispose doesn't get called.

As a workaround I made every service listen for environment.runtime.stopped or crashed to dispose itself.

[lauckhart]

This ask makes sense, our intent is definitely for cleanup to be covered by the environment. It's possible RuntimeService already covers what you're looking for.

Originally the intent was for the environment to "own" services and I think the asyncDispose interface method is an artifact of that. However this meant there's no way to make an external component available as a dependency without assigning ownership. So we added RuntimeService to allow components or their owners to explicitly opt in to ownership assignment.

Rather than listening to env.runtime.stopped you can add your component to the runtime via env.runtime.add. Then it is destroyed when the runtime shuts down, including via RuntimeService#interrupt which runs when you signal the process.

So my inclination is that we should just remove Symbol.asyncDispose from Environmental.Service and you get what you want via RuntimeService.

Which isn't to say we can't consider adding a "close" concept to Environment.ts... Just need to think through the "publish without assigning ownership" case and how to differentiate environment close from runtime cancel. Maybe we could add an additional symbol property to Environmental.Service that informs the environment it should add a service to the runtime automatically?

[lauckhart]

Sure, here's an example:

const myComponent = {
    close() {
        console.log("I'm destroyed");
    }
}
env.runtime.add(myComponent);
// Now when runtime stops myComponent is destroyed

By "own" I just mean "if I'm destroyed you are destroyed too".

You can ignore the typing for RuntimeService.Worker if you want, it just defines contracts RuntimeService understands that workers may implement. The alternative would be to have workers typed as {} which tbh may be clearer.

[t0bst4r]

Okay got it, thank you!
But then I'll add them to both environment (for dep injection and ensuring initilization with env.load) and runtime (for destruction) ?

[lauckhart]

Yes, you use runtime.add to register for destruction (and prevent the runtime from shutting down prematurely).

You don't necessarily need to manually add a component to the environment... If it implements [Environmental.create] the environment will create it for you.

The idea is a component can specify "default" behavior as follows:

class MyService {
    // This is default behavior but caller may override by instantiating manually
    static [Environmental.create](env: Environment) {
        const instance = new MyClass();

        // By default I am a singleton in this environment
        env.set(MyClass, instance);

        // By default I want the environment to destroy me when it stops
        env.runtime.add(instance);
    }
}

[t0bst4r]

Okay got it!
I did it exactly like this before, I just used env.runtime.stopped and crashed for deconstruction instead of just adding it to the runtime.
Thank you! 🙏

Additionally I found that when the environment calls Environmental.create within env.get, it adds the service to itself, too. So in the end env.set is called twice with the exact same params - so it should not have any impact.

But is there any reason for this?

[lauckhart]

No, just artifacts of iterative development. 🙂 At some point we'll decide if it should be the default or not.