Document undocumented WServer member functions
While looking for a way to programmatically stop WServer, I have noticed that these functions are not documented and not available in Doxygen documentation:
These are the ones I notices. There is at least one function(e.g.
WServer::terminate()) whose existence is platform-dependent.
WServer::scheduleStop() is very interesting: Calling
WServer::stop() doesn't cause
WServer::run() to return because, AFAIK,
WServer::waitForShutdown() remains blocked.
WServer::scheduleStop() seems to be the correct way to properly stop the server programmatically and return from
main(). In fact it seems that calling
WServer::waitForShutdown() is blocked renders the server unusable because calling
WServer::resume() doesn't work as expected or shoulkdn't be called in this scenario. Server starts to accept connections, but instead of the applicaton an empty page is served. Readding the application with
WServer::addEntryPoint() before calling
WServer::resume() also doesn't change the outcome.
WServert::start() instead of
WServer::resume() is also not a solution. Consider the following log messages:
[2017-Mar-16 14:46:41.382526] 5852 - [info] "WServer/wthttp: Shutdown: stopping web server." [2017-Mar-16 14:46:51.372525] 5852 - [error] "WServer/wthttp: start(): server already started!"
It would be useful for users if a discussion of programmatic shutdown of WServer was added to WServer documentation and/or Library overview. IMHO, better documentation for
WServer::resume() is also needed.
Updated by Roel Standaert over 5 years ago
The functions you list are intentionally left undocumented, as they are an implementation detail rather than part of the API.
scheduleStop simply sends a terminate signal to the process, equivalent to pressing ctrl+C.
Instead of using
WServer::waitForShutdown(), you could wait for some condition that you update from within a WApplication instance.
Updated by Kayra Akman over 5 years ago
l found all these functions while trying to find a way to periodically stop the server and reinstantiate it without terminating the process. While I used only
scheduleStop() in my code, I listed all of them since they were together in the class definition.
What led me to write this request is this: While Wt tries to provide a convenient way for common tasks, there is not a documented way to programatically "stop" WServer, meaning
WServer::waitForShutdown(), to return.
WServer::waitForShutdown() is the only way Wt provides to block the
WServer::scheduleStop() is the only cross-platform function to unblock it, therefore it deserves to be documented.
What you suggested as a replacement for
WServer::waitForShutdown() is already implemented in WServer with
terminate() etc. and available to users, but just not documented. My point is that users can keep using the recommended
WServer::run() without implementing a
waitForShutdown() replacement since a working unblocking function is already available. Also, the name
waitForShutdown() doesn't sound like an external trigger is the only way to close the server, an internal trigger is also possible IMO and
scheduleStop() is a fine name considering, in practice, it is the counterpart of
WServer::run(). If I would have to make a suggestion,
WServer::quit() could be added as the documented API, just calling
scheduleStop() as long as the
WServer::run() implementation remains as it is.
"Documenting" means making a function not just an implementation detail but a supported, official API that will be kept around for a long time. So I am actually requesting promotion for
scheduleStop(), not just a couple of sentences which I personally don't need after reading the source code. I should have kept this feature request limited to
scheduleStop() and used a proper title.