C/S框架 st_asio_wrapper 开发教程——了解st_asio_wrapper（2019.10.17更新）

一：什么是st_asio_wrapper & ascs

它是一个c/s网络编程框架，基于对boost.asio的包装（最低要求：boost-1.49.0 + gcc-3.4.6(仍未找到最低支持版本，缺少测试环境) / Clang(未寻找最低支持版本，只尝试过3.4.1——一个很新的版本) / vc2008），目的是快速的构建一个c/s系统；ascs和st_asio_wrapper功能完全一样，只是ascs不依赖boost（但可以与boost一起使用），且需要c++11的支持（对于vc来说，至少需要vc2013），在满足ascs最低依赖条件时，我推荐使用ascs，它在编译和运行速度上都要快于st_asio_wrapper。

二：st_asio_wrapper的特点

效率高、跨平台、完全异步，当然这是从boost.asio继承而来；
自动重连，数据透明传输，自动解决分包粘包问题（必须使用默认的打包解包器，这一特性表现得与udp一样）；
内部提供缓存支持；
支持运行时替换打包解包器；
支持ssl。
支持VC, gcc和clang。
原生支持异步消息收发，支持同步消息收发（用异步模拟）。
只支持tcp和udp协议；

三：st_asio_wrapper的大体结构

config.h:
编译器版本测试，更新日志等以及所有支持的宏（如果某个宏默认不开启，也会在这个文件里面，只是是注释状态）；

base.h:
存放一些接口（比如打包解包器接口）、全局类、辅助类、函数以及日志输出等；

service_pump.h(class service_pump):
asio的io_servie（又名io_context）包装类，用于运行st_asio_wrapper的所有service对象（tcp::server_base, tcp::single_client_base, tcp::multi_client_base, udp::single_socket_service_base, udp::multi_socket_service_base, ssl::server_base, ssl::single_client_base, ssl::multi_client_base）；

executor.h(class executor), tracked_executor.h(class tracked_executor):
最顶级父类，主要工作是hook异步调用（以防止异步调用还未回调或者放弃的时候就释放或者重用对象）；

timer.h(class timer，派生于executor或者tracked_executor类):
定时器类；

socket.h(class socket，派生于timer类):
tcp::socket_base和udp::socket_base的基类，主要负责消息收发逻辑（不做实际收发），消息派发、启停等相关功能；

tcp/socket.h(class socket_base，派生于socket类):
tcp套接字类，用于tcp数据的收发；

udp/socket.h(class socket_base，派生于socket类):
udp套接字类，用于udp数据的收发；

object_pool.h(class object_pool，派生于timer类):
对象池，创建和重用对象，维护对象生命周期；

tcp/server.h(class server_base，派生于object_pool类):
服务端对象，用于服务端的监听、接受客户端请求等；

tcp/server_socket.h(class server_socket_base，派生于tcp::socket_base类):
实现服务端相关逻辑；

tcp/client_socket.h(class client_socket_base，派生于tcp::socket类):
实现客户端相关逻辑（比如连接与重连等）；

socket_service.h(class single_socket_service，派生于tcp或者udp的socket_base类, class multi_socket_service，派生于object_pool类):
可以被service_pump类管理的，包涵单个socket和多个socket对象的service类；

tcp/client.h(class single_client_base，派生于single_socket_service类，class multi_client_base，派生于multi_socket_base类):
tcp单连接和多连接客户端；

udp/socket_service.h(class single_socket_service_base派生于single_socket_service类，class multi_socket_service_base，派生于multi_socket_base类):
udp单套接字和多套接字服务；

tcp/ssl/ssl.h(client_socket_base, server_socket_base, server_base, single_client_base, multi_client_base):
st_asio_wrapper库支持的ssl相关的所有类；

ext目录:
主要存放各种各样的打包解包器，辅助类，以及一些方便的定义，比如把需要模板参数的client_socket_base类定义成不需要模板参数的client_socket类（所有以_base结尾的类，都有一个typedef，以定义一个不带_base结尾，且不带任何模板参数的类）等；

四：源代码及demo下载地址

git:https://github.com/youngwolf-project/st_asio_wrapper/，ascs位置与st_asio_wrapper平级。
QQ交流群：198941541 这里面有各个版本供下载。
其中include文件夹里面是st_asio_wrapper的所有类、client和echo_server配合用于演示最简单的数据收发、file_server和file_client用于演示文件传送、echo_client和echo_server配合用于性能测试、pingpong_client和pingpong_server配合用于乒乓测试、concrrent_client和concurrent_server配合用于并发测试、udp_test演示udp通信、ssl_test演示ssl通信，他们都基于st_asio_wrapper；

        推荐在可能的情况下，尽量用ascs，它不依赖boost，也就不需要编译boost这个庞大的库，同时编译速度和运行速度都优于st_asio_wrapper，st_asio_wrapper主要用于老的编译系统，比如说历史遗留工程；

五：开发教程（客户端）

客户端直接#include ext/tcp.h，就可实现一个简单的客户端了，如下（摘自client，可能会有改动，以包里面的demo为准）：

//configuration
#define ST_ASIO_SERVER_PORT 9527
#define ST_ASIO_DEFAULT_UNPACKER non_copy_unpacker
//configuration

#include "../include/ext/tcp.h"
using namespace st_asio_wrapper::ext::tcp;

#define QUIT_COMMAND	"quit"
#define RESTART_COMMAND	"restart"
#define RECONNECT_COMMAND "reconnect"

int main(int argc, const char* argv[])
{
	service_pump sp;
	single_client client(sp);

	if (argc > 2)
		client.set_server_addr(atoi(argv[1]), argv[2]);
	else if (argc > 1)
		client.set_server_addr(atoi(argv[1]), ST_ASIO_SERVER_IP);
	else
		client.set_server_addr(ST_ASIO_SERVER_PORT + 100, ST_ASIO_SERVER_IP);

	sp.start_service();
	while(sp.is_running())
	{
		std::string str;
		std::cin >> str;
		if (QUIT_COMMAND == str)
			sp.stop_service();
		else if (RESTART_COMMAND == str)
		{
			sp.stop_service();
			sp.start_service();
		}
		else if (RECONNECT_COMMAND == str)
			client.graceful_shutdown(true);
		else
			client.safe_send_msg(str, false);
	}

	return 0;
}

以上例子中，客户端从控制台接收数据，调用safe_send_msg发送数据；当收到数据时，会输出到控制台（st_asio_wrapper::socket实现）；

        其中，start_service开启服务，stop_service结束服务（退出时必须明确调用），is_running判断服务的运行状态；如果想修改服务端地址，则在调用start_service之前调用set_server_addr函数；
        stop_service之后，可再次调用start_service开启服务；
        不stop_service而直接想重连接，则以true调用tcp::client_socket_base的force_shutdown或者graceful_shutdown;
      当然，一般来说，客户端不会只把收到的数据显示到控制台这么简单，此时需要从tcp::single_client_base或者udp::single_service_base派生一个类（如果你有多条连接，则从tcp::client_socket_base或者udp::socket_base派生一个类，并用tcp::multi_client_base或者udp::multi_service_base来管理它，这个请参考echo_client这个demo，它支持多条连接），然后重写on_msg_handle并在里面做消息处理，如果消息被处理，请返回true，否则消息将会被延时一小段时间之后，继续派发（仍然通过这个函数）。
        在消息发送成功之后，你有一次机会得到通知，那就是重写on_msg_send函数，它的参数就是这个消息（注意，是打包后的）；
        每调用一次消息发送函数，对方必定收到一次一模一样的数据，二次开发者不用再考虑分包粘包问题（必须使用我提供的打包解包器），这一特点你完全可以把它当成udp的行为；
        socket里面有发送消息缓存，所以当二次开发者有数据需要发送的时候，可以随时发送（注意缓存满的问题，safe_send_msg保证数据发送成功，当缓存满时会等待）而不用关心当前连接是否已经建立，它会在条件适当的时候，为你发送数据。