boost.asio包装类st_asio_wrapper开发教程——宏（2016.10.8更新）

1.全局宏，服务端客户端均需要：

ST_ASIO_USE_STEADY_TIMER定时器采用boost::asio::steady_timer来实现。ST_ASIO_USE_SYSTEM_TIMER定时器采用boost::asio::system_timer来实现，否则将采用boost::asio::deadline_timer来实现。ST_ASIO_MSG_BUFFER_SIZE用于解包的缓存大小，默认4000。它应该大于等于最长的消息包（打包后），拿默认的packer来说，它最大仅支持3998消息长度，因为还有一个2字节的包头。对于默认打包解包器，这个值的范围只能是1至65536，因为包头只用了两个字节来表达长度，如果想要超过这个限制，可定义HUGE_MSG宏。这个缓存越大，那么一次可接收的消息越多（如果SOCKET的缓存里面有数据的话），但不是越大越好，因为每一个解包器里面都有一个大小固定为MSG_BUFFER_SIZE的缓存（不管你用到了多少），而每一个st_tcp_socket都会有一个解包器（st_udp_socket类似），所以这个值越大，占用的内存也就越大。当然，如果你自定义了打包解包器，那上面等于没说，怎么控制内存分配由你说了算。ST_ASIO_HUGE_MSG开启大消息支持，默认关闭。注意，大消息会占用更多内存，请看asio_client这个demo，里面有演示用法（注释状态），以及对于占用更多内存的解释。ST_ASIO_MAX_MSG_NUM每个st_socket消息缓存最大消息条数（接收和发送缓存共用，所以总的最大消息条数是2倍的MAX_MSG_NUM），默认1024。注意这个缓存不会像ST_ASIO_MSG_BUFFER_SIZE一样预分配，而是用到多少分配多少。ST_ASIO_ENHANCED_STABILITY增强的健壮性，如果开启这个宏，所有service对象都会在最外层（io_service::run）包一层try catch，以增加健壮性（当然，增加try  catch 是会有效率损失的），当捕捉到异常的时候，会回调on_exception虚函数，用户通过该函数的返回值来控制是否继续调用io_service::run；另外还可以绝对保证对象被重用或者释放时，没有任何正在进行中的异步调用，在不定义这个宏的情况下，重用或者释放对象时，无法保证所有的异步调用都已经结束，只能通过延时一定的时间；具体请参看ST_ASIO_OBSOLETED_OBJECT_LIFE_TIME宏。ST_ASIO_FORCE_TO_USE_MSG_RECV_BUFFER始终使用消息接收缓存，这个是编译期优化，前面说了，on_msg()返回false代表使用消息接收缓存，如果你的on_msg()永远返回false，则可以开启这个宏，那么st_tcp_socket或者st_udp_socket将不再调用on_msg()（根本不存在这个虚函数了）而是直接将消息放入消息接收缓存，这样可以提高一些效率，默认不开启本宏。ST_ASIO_WANT_MSG_SEND_NOTIFY每次消息发送成功之后（成功送到本地SOCKET缓存），回调on_msg_send虚函数。ST_ASIO_WANT_ALL_MSG_SEND_NOTIFY当发送缓存发空了之后，回调on_all_msg_send虚函数。ST_ASIO_UNIFIED_OUT_BUF_NUM输出日志时用的缓存大小，注意是在栈上分配，注意栈溢出问题，如果你自定义了日志输出，该宏显然无意义。ST_ASIO_NO_UNIFIED_OUT让st_asio_wrapper里面的所有输出失效。ST_ASIO_CUSTOM_LOG自定义输出，此时你需要提供5个日志函数，函数名和签名参看unified_out类，且要么是静态的，要么是全局的。ST_ASIO_FULL_STATISTIC详细的统计信息，包括时间消耗，如果不定义，所有时间消耗项都被不统计。统计的内容有请参看st_socket::statistic类的定义。ST_ASIO_DEFAULT_PACKER自定义打包器，它是一个类名，必须提供默认构造函数（即没有参数的构造函数）。ST_ASIO_DEFAULT_UNPACKER自定义解包器，它是一个类名，必须提供默认构造函数（即没有参数的构造函数）。ST_ASIO_SERVICE_THREAD_NUMIO线程数量，用于运行io_service.run函数，所有回调函数（以on_开头的虚函数）都将会在这些线程中的某一个中被回调。ST_ASIO_MAX_OBJECT_NUM对象池最多支持的对象数量，默认4096。ST_ASIO_REUSE_OBJECT是否开启对象池，如果开启，当创建新对象时，将尝试使用已经被关闭的对象，此时将不会自动定时的释放被关闭的对象链表，请参看ST_ASIO_FREE_OBJECT_INTERVAL宏，默认不开启本宏。ST_ASIO_FREE_OBJECT_INTERVAL说这个宏之前，要说一下st_object_pool的内部工作原理：当调用del_object的时候（st_server_socket在on_recv_error里面的默认行为），st_object_pool的作法并不是删除这个对象，而是把这个对象移动到另外一个链表里面，这个链表里面的对象会被每ST_ASIO_FREE_OBJECT_INTERVAL秒遍历一次，以找到已经真正关闭了的对象（所谓真正关闭，就是已经被close了，而不仅仅是被shutdown了的对象，且没有任何未完成的异步调用），然后真正的从内存中释放它，原因是当del_object的时候，可能还有其它的异步操作还没完成，或者完成了，但还在队列中没有被分发，如果此时从内存中释放对象，那么后面的异步回调的时候，可能会出现内存访问越界。如果未定义ST_ASIO_REUSE_OBJECT宏，ST_ASIO_FREE_OBJECT_INTERVAL宏会被自动定义（如果未显示定义的话）。单位为秒，默认10秒。ST_ASIO_CLEAR_OBJECT_INTERVAL定时循环调用clear_obsoleted_object()以清除失效对象（移动到另外一个链表里面），如果在连接断开时你不方便调用del_object，则对象池里面将会累积越来越多的失效对象（如果有连接出错，或者退出的话），你可以打开这个宏，让st_object_pool为你定时的做这些清除工作；注意，如果对象链表非常大，遍历链表是会影响效率的，如果你的连接是短连接，推荐开启这个功能（那你就不要再任何地方调用del_object了），这样一次可清除多条连接，否则不推荐。单位为秒，该宏默认不开启。ST_ASIO_DELAY_CLOSE关闭连接（shutdown）多少秒钟之后，可以安全释放对象或者重用对象（取决于ST_ASIO_REUSE_OBJECT是否被定义，定义了就是重用，否则释放）。注意如果定义了ST_ASIO_ENHANCED_STABILITY宏，则这个宏将始终为0，因为st_asio_wrapper库可以保证在没有任何异步调用之后才释放或者重用对象。ST_ASIO_DISCARD_MSG_WHEN_LINK_DOWN当连接断开时，如果消息接收缓存里面还有未派发的消息，是否继续派发。那么如何知道消息是正常派发还是因为连接断开而派发的呢，答案是on_msg_handle里面有一个link_down参数，如果为真就是连接断开时的派发，此时就算on_msg_handle返回假，也不会继续再派生这个消息，而是直接派发下一个，因为在连接断开时，需要尽快处理完剩余数据。该宏默认不开启。ST_ASIO_GRACEFUL_SHUTDOWN_MAX_DURATION优雅关闭时，最长等待时间，单位为秒，默认5。ST_ASIO_INPUT_QUEUE指定输入队列（send_msg用到的队列），目前有带锁和不带锁（线程不安全，所以需要你的业务保证线程的安全性）两种队列。ST_ASIO_INPUT_CONTAINER指定输入队列所使用的容器，比如list、deque等，也可以是你自己的容器，只要提供必要的接口。ST_ASIO_OUTPUT_QUEUE指定输出队列，目前有带锁和不带锁（线程不安全，所以需要你的业务保证线程的安全性）两种队列。ST_ASIO_OUTPUT_CONTAINER指定输出队列所使用的容器，比如list、deque等，也可以是你自己的容器，只要提供必要的接口。

2.tcp客户端专用宏：

ST_ASIO_SERVER_IP服务器IP地址，用字符串形式表示，默认"127.0.0.1"ST_ASIO_SERVER_PORT服务器端口，默认5050。ST_ASIO_RECONNECT_INTERVAL当连接服务器失败时，延时多长时间重连，负数表示不重连，单位是毫秒，默认500毫秒。

3.tcp服务端专用宏：

ST_ASIO_SERVER_PORT服务器端口（服务器IP如果要设置的话，只能调用set_server_addr接口，不能通过宏来实现），默认5050。ST_ASIO_TCP_DEFAULT_IP_VERSION在不指定服务端IP时，通过这个宏指定IP协议的版本（v4还是v6，取值分别是boost::asio::ip::tcp::v4()和boost::asio::ip::tcp::v6()），如果指定了IP，则版本从IP地址中分析得来。ST_ASIO_ASYNC_ACCEPT_NUM最多同时投递多少个异步accept调用，默认1。ST_ASIO_NOT_REUSE_ADDRESS关闭端口重用，udp也用使用此宏。

4.udp客户端专用宏：

ST_ASIO_UDP_DEFAULT_IP_VERSION在不指定IP时，通过这个宏指定IP协议的版本（v4还是v6，取值分别是boost::asio::ip::udp::v4()和boost::asio::ip::udp::v6()），如果指定了IP，则版本从IP地址中分析得来。

以上宏都可以按工程为单位来修改，你只需要在include相应st_asio_wrapper相关头文件之前，定义这些宏即可，具体例子demo里面都有。