Feature #5604
openDocument undocumented WServer member functions
0%
Description
While looking for a way to programmatically stop WServer, I have noticed that these functions are not documented and not available in Doxygen documentation:
-
WServer::expireSessions() -
WServer::configuration() -
WServer::controller() -
WServer::scheduleStop()
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::stop() while 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::stop() and WServer::resume() is also needed.
Files
Updated by Roel Standaert about 7 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.
Regards,
Roel
Updated by Kayra Akman about 7 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::run() and WRun(), actually WServer::waitForShutdown(), to return. WServer::waitForShutdown() is the only way Wt provides to block the main() function. 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 scheduleStop(), 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.