Amend annotations.

examples/echo_client/echo_client.cpp

@@ -119,7 +119,8 @@ protected:
 	{
 		ascs::do_something_to_all(msg_can, [this](out_msg_type& msg) {this->handle_msg(msg);});
 		auto re = msg_can.size();
-		msg_can.clear(); //if we left behind some messages in msg_can, they will be dispatched via on_msg_handle and disorder messages
+		msg_can.clear(); //if we left behind some messages in msg_can, they will be dispatched via on_msg_handle asynchronously, which means it's
+		//possible that on_msg_handle be invoked concurrently with the next on_msg (new messages arrived) and then disorder messages.
 		//here we always consumed all messages, so we can use sync message dispatching, otherwise, we should not use sync message dispatching
 		//except we can bear message disordering.
 

examples/echo_server/echo_server.cpp

@@ -110,14 +110,14 @@ protected:
 		if (!is_send_buffer_available())
 			return 0; //congestion control
 		//here if we cannot handle all messages in msg_can, do not use sync message dispatching except we can bear message disordering,
-		//this is because on_msg_handle will be invoked asynchronously, then disorder messages. and do not try to handle all messages
-		//here (just for echo_server's business logic) because:
+		//this is because on_msg_handle can be invoked concurrently with the next on_msg (new messages arrived) and then disorder messages.
+		//and do not try to handle all messages here (just for echo_server's business logic) because:
 		//1. we can not use safe_send_msg as i said many times, we should not block service threads.
 		//2. if we use true can_overflow to call send_msg, then buffer usage will be out of control, we should not take this risk.
 
 		ascs::do_something_to_all(msg_can, [this](out_msg_type& msg) {this->send_msg(msg, true);});
 		auto re = msg_can.size();
-		msg_can.clear(); //if we left behind some messages in msg_can, they will be dispatched via on_msg_handle and disorder messages
+		msg_can.clear();
 
 		return re;
 	}

examples/pingpong_client/pingpong_client.cpp

@@ -52,12 +52,13 @@ protected:
 	virtual void on_connect() {asio::ip::tcp::no_delay option(true); lowest_layer().set_option(option); client_socket::on_connect();}
 
 	//msg handling, must define macro ASCS_SYNC_DISPATCH
-	//do not hold msg_can for further using, access msg_can and return from on_msg_handle as quickly as possible
+	//do not hold msg_can for further using, access msg_can and return from on_msg as quickly as possible
 	virtual size_t on_msg(std::list<out_msg_type>& msg_can)
 	{
 		ascs::do_something_to_all(msg_can, [this](out_msg_type& msg) {this->handle_msg(msg);});
 		auto re = msg_can.size();
-		msg_can.clear(); //if we left behind some messages in msg_can, they will be dispatched via on_msg_handle and disorder messages
+		msg_can.clear(); //if we left behind some messages in msg_can, they will be dispatched via on_msg_handle asynchronously, which means it's
+		//possible that on_msg_handle be invoked concurrently with the next on_msg (new messages arrived) and then disorder messages.
 		//here we always consumed all messages, so we can use sync message dispatching, otherwise, we should not use sync message dispatching
 		//except we can bear message disordering.
 

examples/pingpong_server/pingpong_server.cpp

@@ -38,12 +38,13 @@ public:
 
 protected:
 	//msg handling: send the original msg back (echo server), must define macro ASCS_SYNC_DISPATCH
-	//do not hold msg_can for further using, access msg_can and return from on_msg_handle as quickly as possible
+	//do not hold msg_can for further using, access msg_can and return from on_msg as quickly as possible
 	virtual size_t on_msg(std::list<out_msg_type>& msg_can)
 	{
 		ascs::do_something_to_all(msg_can, [this](out_msg_type& msg) {this->direct_send_msg(std::move(msg));});
 		auto re = msg_can.size();
-		msg_can.clear(); //if we left behind some messages in msg_can, they will be dispatched via on_msg_handle and disorder messages
+		msg_can.clear(); //if we left behind some messages in msg_can, they will be dispatched via on_msg_handle asynchronously, which means it's
+		//possible that on_msg_handle be invoked concurrently with the next on_msg (new messages arrived) and then disorder messages.
 		//here we always consumed all messages, so we can use sync message dispatching, otherwise, we should not use sync message dispatching
 		//except we can bear message disordering.
 

include/ascs/config.h

@@ -744,8 +744,8 @@ static_assert(ASCS_MSG_HANDLING_INTERVAL >= 0, "the interval of msg handling mus
 // this feature is recommended because it can slightly improve efficiency.
 //now we have three ways to handle messages (sync_recv_msg, on_msg and on_msg_handle), the order of handling is the same as listed, if messages been successfully
 // dispatched to sync_recv_msg, then the second two will do nothing, otherwise messages will be dispatched to on_msg, if on_msg only handled a part of (include
-// zero) the messages, then on_msg_handle will continue to dispatch the rest of them (asynchronously, this will disorder messages, please note).
-// as before, on_msg will block the next receiving but only on current socket.
+// zero) the messages, then on_msg_handle will continue to dispatch the rest of them asynchronously, this will disorder messages because on_msg_handle and the next
+// on_msg (new messages arrived) can be invoked concurrently, please note. as before, on_msg will block the next receiving but only on current socket.
 //if you cannot handle all of the messages in on_msg (like echo_server), you should not use sync message dispatching except you can bear message disordering.
 
 //configurations