Allow users to get code run on module shutdown

[riyafa]

Description:
Currently we have a module init function for initialization in modules.We don't have a module stop function concept. It would be useful to have such a function.

In my use case I initialize my mysql client at module init, it would be good to have a module stop function to close it.

Code sample that shows issue:

[jclark]

The requirement is to allow users to get code to run when a module is shutdown. A module stop function would be one way to do that, but I think we can do better.

This relates to #440 and #747, where one of the challenges is to get "sinks" (the thing you send events to) to deal with shutdown properly.

[sanjiva]

We discussed the task module yesterday and again a similar need is present there. This is obviously a graceful shutdown of a module.

[jclark]

The simple (no impact on any other part of the language) way to do this is to provide a runtime:onGracefulStop(StopHandler handler) function, which you can call in init.

[jclark]

We need to decide on order in which these handlers are called relative to each other and relative to the calls to gracefulStop on listeners. Currently the spec doesn't say anything about the relative order of calls to gracefulStop on listeners.

Calls to the init method of a module happen after other initialization of the module but before any listeners are started.

I think the normal thing is to do shutdown in reverse order of initialization, which would imply:

1. gracefulStop on listeners, then
2. call functions registered with gracefulStop in the reverse order in which calls to onGracefulStop were made

[MaryamZi]

I think the normal thing is to do shutdown in reverse order of initialization, which would imply:

1. gracefulStop on listeners, then
2. call functions registered with gracefulStop in the reverse order in which calls to onGracefulStop were made

I agree that gracefulStop on listeners should be called in the reverse order of initialization. But for the StopHandlers (which are registered rather than initialized) with runtime:onGracefulStop, wouldn't it feel natural to call them in the order in which they were registered?

[jclark]

If module A imports module B, then if both module A and module B have an init function that registers a stop handler, then module B's call to onGracefulStop will happen before module A's call, but in my view module destruction should happen in reverse order of module construction (I don't think this is controversial) which means A's stop handler should be called before B's, which corresponds to the reverse of the order in which onGracefulStop is called.

[jclark]

@warunalakshitha I have made the StopHandler return error? for consistency with the gracefulStop method on Listener.

[warunalakshitha]

@jclark Should onGracefulStop be an external function for consistency with registerListener?

https://github.com/ballerina-platform/ballerina-spec/blob/master/lang/lib/runtime.bal#L67

[jclark]

Yes, that's a bug. Thanks.