Register shutdown function to clear event loop

[trowski]

This repeatedly registers shutdown functions which run the event loop until a function does not discover any additional enabled and referenced callbacks in the event loop. The first invocation of the shutdown function always registers another invocation so that any shutdown functions registered during script execution are executed before the second invocation.

There are edge cases where a shutdown function registering another shutdown function which then adds callbacks to the event loop may not be executed, but I consider those cases highly unlikely. I think this will cover every practical use case to avoid unexecuted events on script termination.

Testing shutdown functions in unit tests is difficult, so I added an example which demonstrates the new shutdown behavior.

[danog]

Shouldn't this also check for pending microtasks/queued callbacks?

[trowski]

Yes, you're right. I guess AbstractDriver::isEmpty() also isn't doing that and maybe should (though that function is private and due to how the queue is invoked, I'm not sure there ever can be queued microtasks when isEmpty() is called).

Unfortunately there is nothing on Driver which will let me query if there are queued microtasks, so that would need to be added.

[danog]

In my code, I just unconditionally do

                if (!EventLoop::getDriver()->isRunning()) {
                        $delay = PHP_SAPI === 'cli' ? 5 : 1;
                        $id2 = null;
                        EventLoop::unreference($id1 = EventLoop::delay((float)$delay, static function () use ($delay, &$id2): void {
                                $t = time() - $delay;
                                EventLoop::unreference($id2 = EventLoop::repeat(1.0, static function () use ($t): void {
                                        $t = time() - $t;
                                        Logger::get()->error("Still waiting for shutdown of the event loop for {$t} seconds...");
                                }));
                        }));
                        EventLoop::run();
                        EventLoop::cancel($id1);
                        if ($id2 !== null) {
                                EventLoop::cancel($id2);
                        }
                }

[danog]

i.e. an unconditional run()

[danog]

Something like

EventLoop::unreference(EventLoop::onSignal(SIGINT, function () { throw new SignalException(); }));
getStdin()->read();

will cause a hang here, unless we getStdin()->unreference() in onShutdown (this is how I do it in MadelineProto).

[danog]

While the issue of unreference watchers is generalized, a CTRL-C while reading from STDIN is an especially nasty case for CLI applications, and an extremely common one too.

[bwoebi]

I'm not sure whether we want to happen this unconditionally. I mean, the application may be in an unexpected state upon shutdown being called, especially when the cause is a fatal error or uncaught exception.

I feel like this should be configurable.

Also, how is a server application going to even actually abort on error? (at least unless the shutdown handler then throws or fatals again)

[bwoebi]

... Is it possible to just check whether the cause of shutdown is an error? And if yes, don't run the event loop automatically. Then we also don't need configuration.

(I see, @danog had basically the same concern.)

[trowski]

Well that pretty much spoils this idea. I forgot thrown exceptions would still trigger a shutdown function. Back to the drawing board I suppose. I'm not sure there's a good way to solve this problem outside of recommending applications use EventLoop::run() instead of relying on suspending {main}.

[bwoebi]

@trowski Shouldn't just a simple check for error_get_last()["type"] == E_ERROR (and the other few fatal type errors like E_CORE_ERROR) and such be enough?

[danog]

+1 @bwoebi Yep I share the concerns.

There are two main usecases for this:

1. Partially synchronous (fpm) applications using amphp libraries: since running the event loop will mainly just finish flusing data to sockets, thus the behavior in this PR is very much desired.
   I am using using precisely the behavior of this PR @ work (type 1 partially synchronous application).

2. Fully async applications using EventLoop::run(): running the event loop on shutdown is still needed for the reasons in 1, but it becomes problematic with many independent background fibers each doing async work (and continuing to do so when the event loop is restarted, unless some custom shutdown handler also terminates them)
   MadelineProto is a type 2 application, and re-starts the event loop on shutdown only to do some cleanup, and save state, without actually running EventLoop::run() (because even if my custom shutdown handler terminates MadelineProto-related stuff, there's always the risk of user-specified async logic keeping the event loop alive): https://github.com/danog/MadelineProto/blob/v8/src/Shutdown.php#L59.

In both cases, there is a risk of working with partially corrupted state in case of exceptions, but the benefits of finishing any pending work overweigh the risk (and personally I never encountered issues with this).