[improvement] Improve error handling options for get_connection and start_accept. Update docs. fixes #896

Author: Peter Thorson

changelog.md

@@ -17,6 +17,20 @@ HEAD
   compliant URIs when IPv6 literals are involved. Thank you Jeff Davie, 
   thorsten-klein, mstaz, and barsnick for reporting, example patches, and
   testing. #601 #879
+- Improvement: The error handling system for the server role's async start
+  accept loop and connection generation has been significantly improved. 
+  `endpoint::get_connection` now takes an output parameter ec that gives
+  a detailed error code if connection creation fails. `endpoint::start_accept`
+  now accepts a handler function as a parameter instead of an error code.
+  This handler function allows the client program to be alerted when the
+  async accept loop stops (for any reason, including explicit cancellation)
+  at any time. Previously, it was only possible to tell if the initial loop 
+  start had failed, making it difficult to tell when/if the async accept loop
+  needed to be restarted. The loop handler returns two error codes, a higher
+  level library code and a second more specific transport level code. The
+  old `endpoint::get_connection` and `endpoint::start_accept` functions 
+  remain for backwards compatibility but are deprecated. Thank you Oleh
+  Derevenko for reporting. #896
 - Improvement: Cancel ping timer before calling blocking pong handler.
   This should reduce any unnecessary expiration logic done to a timer
   that is going to be cancelled regardless. Thank you Oleh Derevenko

docs/handlers.dox

@@ -105,6 +105,27 @@ that fail will never have a close handler called.
 Close will be called exactly once for every connection that open was called for.
 Close is not called for failed connections.
 
+Endpoint Handlers
+-----------------
+
+## Acceptance Loop End Handler
+
+| Event                                 | Signature                                                             | Availability                 |
+| ------------------------------------- | --------------------------------------------------------------------- | ---------------------------- |
+| Async Accept Loop end (after opening) | `accept_loop(void(lib::error_code const &, lib::error_code const &))` | 0.9.0 Core, Server role only |
+
+This handler is passed to the `endpoint::start_accept()` function, which initiates an
+asyncronous loop that accepts new connections, and is invoked when that loop ends. The
+handler will be called exactly once for each call of `start_accept` no matter when or
+how it exits (it might exit immediately).
+
+The handler may be called inside the call to `start_accept` if that function has enough
+information to determine that accepting connections will be impossible. Otherwise, it
+may be invoked at a later time from a different asyncronous handler.
+
+The handler returns two error codes. The first from the core library and the second a 
+more detailed code passed through from the underlying transport.
+
 Message Handlers
 ----------------
 

examples/simple_broadcast_server/simple_broadcast_server.cpp

@@ -8,6 +8,7 @@ using websocketpp::connection_hdl;
 using websocketpp::lib::placeholders::_1;
 using websocketpp::lib::placeholders::_2;
 using websocketpp::lib::bind;
+using websocketpp::lib::error_code;
 
 class broadcast_server {
 public:
@@ -27,6 +28,11 @@ class broadcast_server {
         m_connections.erase(hdl);
     }
 
+    void on_end_accept(error_code lib_ec, error_code trans_ec) {
+        std::cout << "Accept loop ended "
+                  << lib_ec.message() << "/" << trans_ec.message() << std::endl;
+    }
+
     void on_message(connection_hdl hdl, server::message_ptr msg) {
         for (auto it : m_connections) {
             m_server.send(it,msg);
@@ -35,7 +41,7 @@ class broadcast_server {
 
     void run(uint16_t port) {
         m_server.listen(port);
-        m_server.start_accept();
+        m_server.start_accept(bind(&broadcast_server::on_end_accept,this,::_1,::_2));
         m_server.run();
     }
 private:

examples/subprotocol_server/subprotocol_server.cpp

@@ -39,7 +39,7 @@ int main() {
 
         s.init_asio();
         s.listen(9005);
-        s.start_accept();
+        s.start_accept(NULL); // omit error handling to keep example consise
 
         s.run();
     } catch (websocketpp::exception const & e) {

examples/telemetry_server/telemetry_server.cpp

@@ -8,6 +8,11 @@
 #include <streambuf>
 #include <string>
 
+using websocketpp::lib::placeholders::_1;
+using websocketpp::lib::placeholders::_2;
+using websocketpp::lib::bind;
+using websocketpp::lib::error_code;
+
 /**
  * The telemetry server accepts connections and sends a message every second to
  * each client containing an integer count. This example can be used as the
@@ -43,8 +48,6 @@ class telemetry_server {
         m_endpoint.init_asio();
 
         // Bind the handlers we are using
-        using websocketpp::lib::placeholders::_1;
-        using websocketpp::lib::bind;
         m_endpoint.set_open_handler(bind(&telemetry_server::on_open,this,_1));
         m_endpoint.set_close_handler(bind(&telemetry_server::on_close,this,_1));
         m_endpoint.set_http_handler(bind(&telemetry_server::on_http,this,_1));
@@ -61,7 +64,7 @@ class telemetry_server {
         m_endpoint.listen(port);
 
         // Start the server accept loop
-        m_endpoint.start_accept();
+        m_endpoint.start_accept(bind(&telemetry_server::on_end_accept,this,_1,_2));
 
         // Set the initial timer to start telemetry
         set_timer();
@@ -85,7 +88,7 @@ class telemetry_server {
         );
     }
 
-    void on_timer(websocketpp::lib::error_code const & ec) {
+    void on_timer(error_code const & ec) {
         if (ec) {
             // there was an error, stop telemetry
             m_endpoint.get_alog().write(websocketpp::log::alevel::app,
@@ -149,7 +152,7 @@ class telemetry_server {
         response.assign((std::istreambuf_iterator<char>(file)),
                         std::istreambuf_iterator<char>());
 
-        con->set_body(response);
+        con->set_body(std::move(response));
         con->set_status(websocketpp::http::status_code::ok);
     }
 
@@ -160,6 +163,11 @@ class telemetry_server {
     void on_close(connection_hdl hdl) {
         m_connections.erase(hdl);
     }
+
+    void on_end_accept(error_code lib_ec, error_code trans_ec) {
+        std::cout << "Accept loop ended "
+                  << lib_ec.message() << "/" << trans_ec.message() << std::endl;
+    }
 private:
     typedef std::set<connection_hdl,std::owner_less<connection_hdl>> con_list;
 

examples/testee_server/testee_server.cpp

@@ -78,6 +78,7 @@ typedef websocketpp::server<testee_config> server;
 using websocketpp::lib::placeholders::_1;
 using websocketpp::lib::placeholders::_2;
 using websocketpp::lib::bind;
+using websocketpp::lib::error_code;
 
 // pull out the type of messages sent by our config
 typedef server::message_ptr message_ptr;
@@ -92,6 +93,12 @@ void on_socket_init(websocketpp::connection_hdl, boost::asio::ip::tcp::socket &
     s.set_option(option);
 }
 
+// Define a callback to handle failures accepting connections
+void on_end_accept(error_code lib_ec, error_code trans_ec) {
+    std::cout << "Accept loop ended "
+                << lib_ec.message() << "/" << trans_ec.message() << std::endl;
+}
+
 int main(int argc, char * argv[]) {
     // Create a server endpoint
     server testee_server;
@@ -122,7 +129,7 @@ int main(int argc, char * argv[]) {
         testee_server.listen(port);
 
         // Start the server accept loop
-        testee_server.start_accept();
+        testee_server.start_accept(&on_end_accept);
 
         // Start the ASIO io_service run loop
         if (num_threads == 1) {