acl/lib_acl/include/aio/acl_aio.h

847 lines
28 KiB
C
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

/**
* @file acl_aio.h
* @author zsx
* @date 2010-1-2
* @brief 本文件中定义了关于 ACL_ASTREAM 异步通信流操作的类型说明及函数接口.
* @version 1.1
*/
#ifndef ACL_AIO_INCLUDE_H
#define ACL_AIO_INCLUDE_H
#ifdef __cplusplus
extern "C" {
#endif
#include "../stdlib/acl_define.h"
#include <stdarg.h>
#ifdef ACL_UNIX
#include <sys/uio.h>
#endif
#include "../stdlib/acl_stdlib.h"
#include "../event/acl_events.h"
/*------------------------------- 数据结构类型定义 ---------------------------*/
/**
* 异步框架引擎句柄类型定义
*/
typedef struct ACL_AIO ACL_AIO;
/**
* 异步流类型定义
*/
typedef struct ACL_ASTREAM ACL_ASTREAM;
/**
* 事件通知函数句柄类型, 当某个受监控的流有数据可读或出错时的回调用户的注册函数,
* 目前用与该类型相关的异步函数有:
* acl_aio_gets, acl_aio_gets_nonl, acl_aio_read, acl_aio_readn.
* @param astream {ACL_ASTREAM*} 异步流指针
* @param context {void*} 用户级传递的参数
* @param data {const char*} 从流中读取的数据指针
* @param dlen {int} data 数据的长度
* @return {int} 该函数指针调用如果返回-1则表明应用要求关闭异步流
*/
typedef int (*ACL_AIO_READ_FN)(ACL_ASTREAM *astream,
void *context, char *data, int dlen);
/**
* 事件通知函数句柄类型,当某个异步流可读/可写时调用此类型的用户回调函数
* @param astream {ACL_ASTREAM*} 异步流指针
* @param context {void*} 用户级传递的参数
* @return {int} 如果该函数类型返回 -1 则表明应用要求关闭异步流
*/
typedef int (*ACL_AIO_NOTIFY_FN)(ACL_ASTREAM *astream, void *context);
/**
* 事件通知函数句柄类型, 当某个受监控的流将数据写完或出错时的回调用户的注册函数,
* 目前用与该类型相关的异步函数有:
* acl_aio_writen, acl_aio_writev, acl_aio_fprintf, acl_aio_vfprintf.
* @param astream {ACL_ASTREAM*} 异步流指针
* @param context {void*} 用户级传递的参数
* @return {int} 该函数指针调用如果返回-1则表明应用要求关闭异步流
*/
typedef int (*ACL_AIO_WRITE_FN)(ACL_ASTREAM *astream, void *context);
/**
* 当某个监听描述符有新的客户端连接时, 异步框架接收该连接并传递给用户; 如果出错,
* 若用户设置了该监听流的监听超时值且到达该超时值, 则也会触发该函数类型句柄. 与该函数
* 类型句柄相关的异步函数有: acl_aio_accept.
* @param cstream {ACL_ASTREAM*} 从 sstream 监听流通过 accept() 获得的客户端连接流
* @param context {void*} 用户级传递的参数
* @return {int} 如果该函数调用返回 -1 表示不再继续接收新的客户端连接
*/
typedef int (*ACL_AIO_ACCEPT_FN)(ACL_ASTREAM *cstream, void *context);
/**
* 当某个监听描述符上有新的客户端连接时, 异步框架回调用用户的注册函数, 用户需要从
* 该监听流上 accept 该客户端连接. 与该函数类型相关的异步函数有: acl_aio_listen.
* @param sstream {ACL_ASTREAM*} 监听流句柄
* @param context {void*} 用户级传递的参数
* @return {int} 如果该函数的调用返回-1并不影响监听流继续监听
* 注: 请注意该函数类型与 ACL_AIO_ACCEPT_FN 的功能差别.
*/
typedef int (*ACL_AIO_LISTEN_FN)(ACL_ASTREAM *sstream, void *context);
/**
* 异步连接远程服务器时, 当连接失败、超时或成功时的事件通知句柄类型
* 将回调用户的注册函数. 与该函数类型相关的异步函数有: acl_aio_connect.
* @param cstream {ACL_ASTREAM*} 受监控的正处于连接状态的客户端流
* @param context {void*} 用户级传递的参数
* @return {int} 若调用该函数返回-1则需要关闭该异步连接流
*/
typedef int (*ACL_AIO_CONNECT_FN)(ACL_ASTREAM *cstream, void *context);
/**
* “读、写、监听”超时的回调函数指针
* @param astream {ACL_ASTREAM*} 异步流指针
* @param context {void*} 用户传递的参数
* @return {int} 当该函数调用返回-1时对于读写流表示需要关闭该异步读写流
* 对于监听流表示不再继续接收新的客户端连接当返回0时表示继续
*/
typedef int (*ACL_AIO_TIMEO_FN)(ACL_ASTREAM *astream, void *context);
/**
* 当需要关闭异步读写流时需要回调用用户注册的函数
* @param astream {ACL_ASTREAM*} 异步流指针
* @param context {void*} 用户传递的参数
* @return {int} 无论该值如何,该异步流都需要被关闭
*/
typedef int (*ACL_AIO_CLOSE_FN)(ACL_ASTREAM *astream, void *context);
/* 异步流类型定义 */
struct ACL_ASTREAM {
ACL_AIO *aio; /**< 异步流事件句柄 */
ACL_VSTREAM *stream; /**< 同步流 */
ACL_VSTRING strbuf; /**< 内部缓冲区 */
int timeout; /**< IO超时时间 */
int nrefer; /**< 通过此引用计数防止流被提前关闭 */
int flag; /**< 标志位 */
#define ACL_AIO_FLAG_IOCP_CLOSE (1 << 0)
#define ACL_AIO_FLAG_ISRD (1 << 1)
#define ACL_AIO_FLAG_ISWR (1 << 2)
#define ACL_AIO_FLAG_DELAY_CLOSE (1 << 3)
#define ACL_AIO_FLAG_DEAD (1 << 4)
ACL_FIFO write_fifo; /**< 异步写时的先进先出队列数据 */
int write_left; /**< 写缓冲中未写完的数据量 */
int write_offset; /**< 写缓冲中的下一个位置偏移 */
int write_nested; /**< 写时的嵌套层数 */
int write_nested_limit; /**< 写时的嵌套层数限制 */
int (*read_ready_fn) (ACL_VSTREAM *, ACL_VSTRING *, int *);
int read_nested; /**< 读时的嵌套层数 */
int read_nested_limit; /**< 读时的嵌套层数限制 */
int count; /**< 调用 acl_aio_readn()/2 时设置的第二个参数值 */
int keep_read; /**< 是否启用持续性读 */
int accept_nloop; /**< acl_aio_accept 内部循环 accept 的最大次数 */
int error; /**< 当前套接口的错误号 */
int line_length; /**< 当以行为单位读数据时该值限制每行最大长度 */
ACL_AIO_ACCEPT_FN accept_fn; /**< accept 完成时的回调函数 */
ACL_AIO_LISTEN_FN listen_fn; /**< 有新连接到达时的回调函数 */
void *context; /**< 用户设置的参数 */
ACL_AIO_NOTIFY_FN can_read_fn; /**< 可以读时的回调函数 */
void *can_read_ctx; /**< can_read_fn 参数之一 */
ACL_AIO_NOTIFY_FN can_write_fn; /**< 可以写时的回调函数 */
void *can_write_ctx; /**< can_write_fn 参数之一 */
ACL_ARRAY *read_handles; /**< 读完成时的辅助回调函数 */
ACL_ARRAY *write_handles; /**< 写完成时的辅助回调函数 */
ACL_ARRAY *close_handles; /**< 关闭时的辅助回调函数 */
ACL_ARRAY *timeo_handles; /**< 超时时的辅助回调函数 */
ACL_ARRAY *connect_handles; /**< 连接成功时辅助回调函数 */
ACL_FIFO reader_fifo; /**< 临时存放回调函数 */
ACL_FIFO writer_fifo; /**< 临时存放回调函数 */
/* 可读时的回调函数 */
void (*event_read_callback)(int event_type, ACL_ASTREAM *astream);
};
/**
* 设置流的IO超时时间
*/
#define ACL_AIO_SET_TIMEOUT(stream_ptr, _timeo_) do { \
ACL_ASTREAM *__stream_ptr = stream_ptr; \
__stream_ptr->timeout = _timeo_; \
} while(0)
/**
* 设置流的 context 参数
*/
#define ACL_AIO_SET_CTX(stream_ptr, _ctx_) do { \
ACL_ASTREAM *__stream_ptr = stream_ptr; \
__stream_ptr->context = _ctx_; \
} while(0)
/*--------------------------- 异步操作公共接口 -------------------------------*/
/**
* 创建一个异步通信的异步框架实例句柄, 可以指定是否采用 epoll/devpoll
* @param event_mode {int} 事件监听方式: ACL_EVENT_SELECT, ACL_EVENT_POLL
* , ACL_EVENT_KERNEL, ACL_EVENT_WMSG
* @return {ACL_AIO*} 返回一个异步框架引擎句柄. OK: != NULL; ERR: == NULL.
*/
ACL_API ACL_AIO *acl_aio_create(int event_mode);
/**
* 创建异步框架实例句柄, 可以指定是否采用 epoll/devpoll/windows message
* @param event_mode {int} 事件监听方式: ACL_EVENT_SELECT, ACL_EVENT_POLL
* , ACL_EVENT_KERNEL, ACL_EVENT_WMSG
* @param nMsg {unsigned int} 当与 _WIN32 界面的消息整合时,即 event_mode 设为
* ACL_EVENT_WMSG 时该值才有效,其表示与异步句柄绑定的消息值
* @return {ACL_AIO*} 返回一个异步框架引擎句柄. OK: != NULL; ERR: == NULL.
*/
ACL_API ACL_AIO *acl_aio_create2(int event_mode, unsigned int nMsg);
/**
* 根据事件引擎句柄创建异步对象句柄
* @param event {ACL_EVENT *}
* @return {ACL_AIO *}
*/
ACL_API ACL_AIO *acl_aio_create3(ACL_EVENT *event);
/**
* 释放一个异步通信异步框架实例句柄,同时会释放掉非空的 aio->event 对象
* @param aio {ACL_AIO*} 异步框架引擎句柄
*/
ACL_API void acl_aio_free(ACL_AIO *aio);
/**
* 释放一个异步通信异步框架实例句柄
* @param keep {int} 是否同时释放掉 aio 所绑定的 event 事件句柄
* @param aio {ACL_AIO*} 异步框架引擎句柄
*/
ACL_API void acl_aio_free2(ACL_AIO *aio, int keep);
/**
* 异步IO消息循环(仅在单线程模式下调用)
* @param aio {ACL_AIO*} 异步框架引擎句柄
*/
ACL_API void acl_aio_loop(ACL_AIO *aio);
/**
* 获得本次事件循环被触发的事件次数
* @param aio {ACL_AIO*} 异步框架引擎句柄
* @return {int} -1 表示输入参数有误,否则返回值 >= 0
*/
ACL_API int acl_aio_last_nready(ACL_AIO *aio);
/**
* 主动检查 ACL_AIO 引擎中待关闭的异步流是否应该关闭,调用此函数后,一些需要
* 延迟关闭的异步流会被主动关闭
* @param aio {ACL_AIO*} 异步框架引擎句柄
*/
ACL_API void acl_aio_check(ACL_AIO *aio);
/**
* 获得事件引擎的句柄
* @param aio {ACL_AIO*} 异步框架引擎句柄
* @return {ACL_EVENT*}
*/
ACL_API ACL_EVENT *acl_aio_event(ACL_AIO *aio);
/**
* 获得事件所采用的模式
* @param aio {ACL_AIO*} 异步框架引擎句柄
* @return {int} ACL_EVENT_KERNEL/ACL_EVENT_SELECT/ACL_EVENT_POLL
*/
ACL_API int acl_aio_event_mode(ACL_AIO *aio);
/**
* 异步IO框架是否是采用持续读模式
* @param aio {ACL_AIO*} 异步框架引擎句柄
* @return {int} != 0: 是; == 0: 否
*/
ACL_API int acl_aio_get_keep_read(ACL_AIO *aio);
/**
* 设置异步IO框架的持续读模式
* @param aio {ACL_AIO*} 异步框架引擎句柄
* @param onoff {int} 0: 关闭持续读功能; != 0: 打开持续读功能
*/
ACL_API void acl_aio_set_keep_read(ACL_AIO *aio, int onoff);
/**
* 获得当前异步引擎循环时的等待时间的秒部分
* @param aio {ACL_AIO*} 异步框架引擎句柄
* @return {int} 用 select/poll/epoll/kqueue/devpoll 时的秒级等待时间
*/
ACL_API int acl_aio_get_delay_sec(ACL_AIO *aio);
/**
* 获得当前异步引擎循环时的等待时间的微秒部分
* @param aio {ACL_AIO*} 异步框架引擎句柄
* @return {int} 用 select/poll/epoll/kqueue/devpoll 时的微秒级等待时间
*/
ACL_API int acl_aio_get_delay_usec(ACL_AIO *aio);
/**
* 设置异步引擎循环的等待时间中的秒级部分
* @param aio {ACL_AIO*} 异步框架引擎句柄
* @param delay_sec {int} 设置用 select/poll/epoll/kqueue/devpoll
* 时的秒级等待时间
*/
ACL_API void acl_aio_set_delay_sec(ACL_AIO *aio, int delay_sec);
/**
* 设置异步引擎循环的等待时间中的微秒级部分
* @param aio {ACL_AIO*} 异步框架引擎句柄
* @param delay_usec {int} 设置用 select/poll/epoll/kqueue/devpoll
* 时的微秒级等待时间
*/
ACL_API void acl_aio_set_delay_usec(ACL_AIO *aio, int delay_usec);
/**
* 设置事件循环过程中定时检查所有描述字状态的时间间隔,内部缺省值为 100 ms
* @param aio {ACL_AIO*} 异步框架引擎句柄
* @param check_inter {int} 定时查检时间间隔 (毫秒级)
*/
ACL_API void acl_aio_set_check_inter(ACL_AIO *aio, int check_inter);
/**
* 设置异步流的读缓存区大小
* @param aio {ACL_AIO*} 异步框架引擎句柄
* @param rbuf_size {int} 读缓冲区大小
*/
ACL_API void acl_aio_set_rbuf_size(ACL_AIO *aio, int rbuf_size);
/**
* 设置监听异步流每次接收客户端连接时循环接收个数
* @param astream {ACL_ASTREAM*} 监听流
* @param nloop {int}
*/
ACL_API void acl_aio_set_accept_nloop(ACL_ASTREAM *astream, int nloop);
/**
* 从异步流中获得异步框架引擎句柄
* @param stream {ACL_ASTREAM*} 异步IO流
* @return {ACL_AIO*} 异步框架引擎句柄
*/
ACL_API ACL_AIO *acl_aio_handle(ACL_ASTREAM *stream);
/**
* 设置异步流的参数
* @param stream {ACL_ASTREAM*} 异步IO流
* @param ctx {void*} 参数
*/
ACL_API void acl_aio_set_ctx(ACL_ASTREAM *stream, void *ctx);
/**
* 获得异步流的参数
* @param stream {ACL_ASTREAM*} 异步IO流
* @return {void*} 异步流 stream 的参数
*/
ACL_API void *acl_aio_get_ctx(ACL_ASTREAM *stream);
/**
* 打开一个异步通信流的句柄
* @param aio {ACL_AIO*} 异步框架引擎句柄
* @param stream {ACL_VSTREAM*} 受监控的流, 当该流有完整的一行数据、出错
* 或读超时时将回调用户的注册函数.
* @return {ACL_ASTREAM*} 异步通信流句柄
*/
ACL_API ACL_ASTREAM *acl_aio_open(ACL_AIO *aio, ACL_VSTREAM *stream);
/**
* 异步IO完成后关闭流否则进行异步关闭动作即需要等读写都完成时才关闭流
* @param astream {ACL_ASTREAM*} 异步数据流
*/
ACL_API void acl_aio_iocp_close(ACL_ASTREAM *astream);
/**
* 取消异步IO过程该功能主要是为了将异步IO流转换为同步IO流而写
* @param astream {ACL_ASTREAM*} 异步IO流
* @return {ACL_VSTREAM*} 流句柄
*/
ACL_API ACL_VSTREAM *acl_aio_cancel(ACL_ASTREAM *astream);
/**
* 获得监听描述符每次接收客户端连接的最大个数
* @param astream {ACL_ASTREAM *} 监听描述符流
* @return {int} 每次接收连接的最大个数
* @return {int} 监听描述符在每次接收过程中可以循环接收的最大连接
* 个数此值最小为1
*/
ACL_API int acl_aio_get_accept_max(ACL_ASTREAM *astream);
/**
* 设置监听描述符每次接收客户端连接的最大个数
* @param astream {ACL_ASTREAM *} 监听描述符流
* @param accept_max {int} 监听描述符在每次接收过程中可以循环接收的最大连接
* 个数此值最小为1
*/
ACL_API void acl_aio_set_accept_max(ACL_ASTREAM *astream, int accept_max);
/**
* 添加附加读回调函数
* @param astream {ACL_ASTREAM*} 异步流,不能为空
* @param callback {ACL_AIO_READ_FN} 回调函数,不能为空
* @param ctx {void*} callback 回调函数的回调参数,可以为空
*/
ACL_API void acl_aio_add_read_hook(ACL_ASTREAM *astream,
ACL_AIO_READ_FN callback, void *ctx);
/**
* 添加附加写回调函数
* @param astream {ACL_ASTREAM*} 异步流,不能为空
* @param callback {ACL_AIO_READ_FN} 回调函数,不能为空
* @param ctx {void*} callback 回调函数的回调参数,可以为空
*/
ACL_API void acl_aio_add_write_hook(ACL_ASTREAM *astream,
ACL_AIO_WRITE_FN callback, void *ctx);
/**
* 添加附加关闭回调函数
* @param astream {ACL_ASTREAM*} 异步流,不能为空
* @param callback {ACL_AIO_READ_FN} 回调函数,不能为空
* @param ctx {void*} callback 回调函数的回调参数,可以为空
*/
ACL_API void acl_aio_add_close_hook(ACL_ASTREAM *astream,
ACL_AIO_CLOSE_FN callback, void *ctx);
/**
* 添加附加超时回调函数
* @param astream {ACL_ASTREAM*} 异步流,不能为空
* @param callback {ACL_AIO_READ_FN} 回调函数,不能为空
* @param ctx {void*} callback 回调函数的回调参数,可以为空
*/
ACL_API void acl_aio_add_timeo_hook(ACL_ASTREAM *astream,
ACL_AIO_TIMEO_FN callback, void *ctx);
/**
* 添加附加连接成功回调函数
* @param astream {ACL_ASTREAM*} 异步流,不能为空
* @param callback {ACL_AIO_READ_FN} 回调函数,不能为空
* @param ctx {void*} callback 回调函数的回调参数,可以为空
*/
ACL_API void acl_aio_add_connect_hook(ACL_ASTREAM *astream,
ACL_AIO_CONNECT_FN callback, void *ctx);
/**
* 删除附加读回调函数
* @param astream {ACL_ASTREAM*} 异步流,不能为空
* @param callback {ACL_AIO_READ_FN} 回调函数,不能为空
* @param ctx {void*} callback 回调函数的回调参数,可以为空
*/
ACL_API void acl_aio_del_read_hook(ACL_ASTREAM *astream,
ACL_AIO_READ_FN callback, void *ctx);
/**
* 删除附加写回调函数
* @param astream {ACL_ASTREAM*} 异步流,不能为空
* @param callback {ACL_AIO_READ_FN} 回调函数,不能为空
* @param ctx {void*} callback 回调函数的回调参数,可以为空
*/
ACL_API void acl_aio_del_write_hook(ACL_ASTREAM *astream,
ACL_AIO_WRITE_FN callback, void *ctx);
/**
* 删除附加关闭回调函数
* @param astream {ACL_ASTREAM*} 异步流,不能为空
* @param callback {ACL_AIO_READ_FN} 回调函数,不能为空
* @param ctx {void*} callback 回调函数的回调参数,可以为空
*/
ACL_API void acl_aio_del_close_hook(ACL_ASTREAM *astream,
ACL_AIO_CLOSE_FN callback, void *ctx);
/**
* 删除附加超时回调函数
* @param astream {ACL_ASTREAM*} 异步流,不能为空
* @param callback {ACL_AIO_READ_FN} 回调函数,不能为空
* @param ctx {void*} callback 回调函数的回调参数,可以为空
*/
ACL_API void acl_aio_del_timeo_hook(ACL_ASTREAM *astream,
ACL_AIO_TIMEO_FN callback, void *ctx);
/**
* 删除附加连接成功回调函数
* @param astream {ACL_ASTREAM*} 异步流,不能为空
* @param callback {ACL_AIO_READ_FN} 回调函数,不能为空
* @param ctx {void*} callback 回调函数的回调参数,可以为空
*/
ACL_API void acl_aio_del_connect_hook(ACL_ASTREAM *astream,
ACL_AIO_CONNECT_FN callback, void *ctx);
/**
* 清除所有的附加读回调函数
* @param astream {ACL_ASTREAM*} 异步流,不能为空
*/
ACL_API void acl_aio_clean_read_hooks(ACL_ASTREAM *astream);
/**
* 清除所有的附加写回调函数
* @param astream {ACL_ASTREAM*} 异步流,不能为空
*/
ACL_API void acl_aio_clean_write_hooks(ACL_ASTREAM *astream);
/**
* 清除所有的附加关闭回调函数
* @param astream {ACL_ASTREAM*} 异步流,不能为空
*/
ACL_API void acl_aio_clean_close_hooks(ACL_ASTREAM *astream);
/**
* 清除所有的附加超时回调函数
* @param astream {ACL_ASTREAM*} 异步流,不能为空
*/
ACL_API void acl_aio_clean_timeo_hooks(ACL_ASTREAM *astream);
/**
* 清除所有的附加连接成功回调函数
* @param astream {ACL_ASTREAM*} 异步流,不能为空
*/
ACL_API void acl_aio_clean_connect_hooks(ACL_ASTREAM *astream);
/**
* 清除所有的附加回调函数
* @param astream {ACL_ASTREAM*} 异步流,不能为空
*/
ACL_API void acl_aio_clean_hooks(ACL_ASTREAM *astream);
/**
* 设置异步流的属性
* @param astream {ACL_ASTREAM*} 异步流对象
* @param name {int} 第一个控制参数
* @param ... 变参列表格式为ACL_AIO_CTL_XXX, xxx, 最后一个控制参数
* 为 ACL_AIO_CTL_END
*/
ACL_API void acl_aio_ctl(ACL_ASTREAM *astream, int name, ...);
#define ACL_AIO_CTL_END 0 /**< 控制结束标志 */
#define ACL_AIO_CTL_ACCEPT_FN 1 /**< 设置接收连接后回调函数 */
#define ACL_AIO_CTL_LISTEN_FN 2 /**< 设置有连接到达时回调函数 */
#define ACL_AIO_CTL_CTX 3 /**< 设置应用的参数 */
#define ACL_AIO_CTL_TIMEOUT 4 /**< 设置超时时间 */
#define ACL_AIO_CTL_LINE_LENGTH 5 /**< 设置所读行数据的最大长长度 */
#define ACL_AIO_CTL_STREAM 10 /**< 设置ACL_VSTREAM流指针 */
#define ACL_AIO_CTL_READ_NESTED 11 /**< 设置最大读嵌套层数 */
#define ACL_AIO_CTL_WRITE_NESTED 12 /**< 设置最大写嵌套层数 */
#define ACL_AIO_CTL_KEEP_READ 13 /**< 设置是否连续读标志 */
#define ACL_AIO_CTL_READ_HOOK_ADD 14 /**< 添加附加读回调函数 */
#define ACL_AIO_CTL_READ_HOOK_DEL 15 /**< 删除附加读回调函数 */
#define ACL_AIO_CTL_WRITE_HOOK_ADD 16 /**< 添加附加写回调函数 */
#define ACL_AIO_CTL_WRITE_HOOK_DEL 17 /**< 删除附加写回调函数 */
#define ACL_AIO_CTL_CLOSE_HOOK_ADD 18 /**< 添加附加关闭回调函数 */
#define ACL_AIO_CTL_CLOSE_HOOK_DEL 19 /**< 删除附加关闭回调函数 */
#define ACL_AIO_CTL_TIMEO_HOOK_ADD 20 /**< 添加附加超时回调函数 */
#define ACL_AIO_CTL_TIMEO_HOOK_DEL 21 /**< 删除附加超时回调函数 */
#define ACL_AIO_CTL_CONNECT_HOOK_ADD 22 /**< 添加附加连接回调函数 */
#define ACL_AIO_CTL_CONNECT_HOOK_DEL 23 /**< 删除附加连接回调函数 */
/**
* 从异步流中提取 ACL_VSTREAM 流
* @param astream {ACL_ASTREAM*} 异步IO流
* @return {ACL_VSTREAM*} 通信流指针
*/
ACL_API ACL_VSTREAM *acl_aio_vstream(ACL_ASTREAM *astream);
/*---------------------------- 异步读操作接口 --------------------------------*/
/**
* 异步从流中读取一行数据, 当成功读取一行数据、出错、读超时时将回调用户的
* 注册函数: notify_fn
* @param astream {ACL_ASTREAM*} 受监控的流, 当该流有完整的一行数据、出错
* 或读超时时将回调用户的注册函数.
* 注: 读操作发生在异步框架内.
* 当通过 acl_aio_stream_set_line_length 设置了行最大长度限制,则当接收的
* 数据行过大时,为避免缓冲区溢出,该函数的处理过程将会在缓冲区达到该长度
* 限制时被触发,直接将数据交由使用者注册的回调过程
*/
ACL_API void acl_aio_gets(ACL_ASTREAM *astream);
/**
* 异步从流中读取一行数据, 当成功读取一行数据、出错、读超时时将回调用户的
* 注册函数: notify_fn, 与 acl_aio_gets 功能类似, 但唯一的区别是返回的数据
* data 中不包含 "\r\n" 或 "\n", 当读到一个空行时, 则 dlen == 0.
* @param astream {ACL_ASTREAM*} 受监控的流, 当该流有完整的一行数据、出错
* 或读超时时将回调用户的注册函数.
* 注: 读操作发生在异步框架内.
* 数据行过大时,为避免缓冲区溢出,该函数的处理过程将会在缓冲区达到该长度
* 限制时被触发,直接将数据交由使用者注册的回调过程
*/
ACL_API void acl_aio_gets_nonl(ACL_ASTREAM *astream);
/**
* 异步从流中读取数据, 读取的数据格式及长度没有特殊要求.
* @param astream {ACL_ASTREAM*} 处于读监控的流. 当该流出错、超时或已经读取了一定
* 长度的数据时将触发事件通知过程
* 注: 读操作发生在异步框架内.
*/
ACL_API void acl_aio_read(ACL_ASTREAM *astream);
/**
* 异步从流中读取要求长度的数据, 当流出错、超时或读到了所要求的数据长度时将
* 触发事件通知过程
* @param astream {ACL_ASTREAM*} 处于读监控的流. 当该流出错、超时或已经读取了所
* 要求长度的数据时将触发事件通知过程
* @param count {int} 所要求的数据的长度, 必须大于 0.
* 注: 读操作发生在异步框架内.
*/
ACL_API void acl_aio_readn(ACL_ASTREAM *astream, int count);
/**
* 尝试性读取一行数据
* @param astream {ACL_ASTREM*} 异步流对象
* @return {ACL_VSTRING*} 若读得完整一行则返回非空对象,用户用完此 ACL_VSTRING
* 数据后应调用 ACL_VSTRING_RESET(s) 清空缓冲区; 若未读得完整行则返回空
*/
ACL_API ACL_VSTRING *acl_aio_gets_peek(ACL_ASTREAM *astream);
/**
* 尝试性读取一行数据(不包含 \n 或 \r\n)
* @param astream {ACL_ASTREM*} 异步流对象
* @return {ACL_VSTRING*} 若读得完整一行则返回非空对象,用户用完此 ACL_VSTRING
* 数据后应调用 ACL_VSTRING_RESET(s) 清空缓冲区, 另外如果读到一个空行,则返回的
* ACL_VSTRING 的缓冲区的数据长度(ACL_VSTRING_LEN 获得此值) 应为 0;
* 若未读得完整行则返回空
*/
ACL_API ACL_VSTRING *acl_aio_gets_nonl_peek(ACL_ASTREAM *astream);
/**
* 尝试性从异步流中读取数据,如果有数据则返回没有则返回空
* @param astream {ACL_ASTREM*} 异步流对象
* @return {ACL_VSTRING*} 若读到了数据则返回的缓冲区非空(使用者用完此缓冲区后
* 需要调用 ACL_VSTRING_RESET(s) 清空此缓冲区), 否则返回空
*/
ACL_API ACL_VSTRING *acl_aio_read_peek(ACL_ASTREAM *astream);
/**
* 尝试性从异步流中读给定长度的数据,如果读到的数据满足要求则返回缓冲区
* @param astream {ACL_ASTREM*} 异步流对象
* @param count {int} 要求读到的数据长度
* @return {ACL_VSTRING*} 若读到规定长度则返回非空缓冲区(使用者用完此缓冲区后
* 需要调用 ACL_VSTRING_RESET(s) 清空此缓冲区), 否则返回空
*/
ACL_API ACL_VSTRING *acl_aio_readn_peek(ACL_ASTREAM *astream, int count);
/**
* 设置异步流为读监听状态,当该流可读时则调用用户的回调函数
* @param astream {ACL_ASTREM*} 异步流对象
* @param can_read_fn {ACL_AIO_NOTIFY_FN} 用户回调函数
* @param context {void*} can_read_fn 的参数之一
*/
ACL_API void acl_aio_enable_read(ACL_ASTREAM *astream,
ACL_AIO_NOTIFY_FN can_read_fn, void *context);
/**
* 检测异步流有多少数据可读
* @param astream {ACL_ASTREM*} 异步流对象
* @return {int} ACL_VSTREAM_EOF 表示出错,应该关闭该流; 0 表示无数据可读;
* > 0 表示有数据可读
*/
ACL_API int acl_aio_can_read(ACL_ASTREAM *astream);
/**
* 停止对一个数据流进行IO读操作
* @param astream {ACL_ASTREAM*} 异步数据流
*/
ACL_API void acl_aio_disable_read(ACL_ASTREAM *astream);
/**
* 判断流是否在异步事件的读监听集合中
* @param astream {ACL_ASTREAM*} 异步数据流
* @return {int} 0: 否,!= 0: 是
*/
ACL_API int acl_aio_isrset(ACL_ASTREAM *astream);
/**
* 设置读一行数据时每行数据的最大长度限制,这样的目的主要是为了防止对方发送的
* 一行数据过长,造成本地接收缓冲区内存溢出
* @param astream {ACL_ASTREAM*} 异步数据流
* @param len {int} 当该值 > 0 时将会限制按行读的数据长度
*/
ACL_API void acl_aio_stream_set_line_length(ACL_ASTREAM *astream, int len);
/**
* 获得所设置的流按行读数据时的最大长度限制
* @param astream {ACL_ASTREAM*} 异步数据流
* @return {int}
*/
ACL_API int acl_aio_stream_get_line_length(ACL_ASTREAM *astream);
/**
* 单独设置异步流的连续读标记,缺省情况下自动继承 ACL_AIO 中的 keep_read
* 标记(其默认情况下是连续读)
* @param astream {ACL_ASTREAM*} 异步数据流
* @param onoff {int} 0 表示关闭连续读功能非0表示打开连续读功能
*/
ACL_API void acl_aio_stream_set_keep_read(ACL_ASTREAM *astream, int onoff);
/**
* 获得异步流是否是设置了连续读标记
* @return {int} 0 表示关闭了连续读功能非0表示打开了连续读功能
*/
ACL_API int acl_aio_stream_get_keep_read(ACL_ASTREAM *astream);
/*---------------------------- 异步写操作接口 --------------------------------*/
/**
* 异步向流中写数据, 当流出错、写超时或写成功时将触发事件通知过程
* @param astream {ACL_ASTREAM*} 处于写监控的流.
* @param data {const char*} 所写数据的内存开始指针位置
* @param dlen {int} data 中数据长度
*/
ACL_API void acl_aio_writen(ACL_ASTREAM *astream, const char *data, int dlen);
/**
* 异步向流中写数据, 当流出错、写超时或写成功时将触发事件通知过程,类似系统的
* writev
* @param astream {ACL_ASTREAM*} 处于写监控的流.
* @param vector {const struct iovec*} 数据集合数组
* @param count {int} vector 数组的长度
*/
ACL_API void acl_aio_writev(ACL_ASTREAM *astream,
const struct iovec *vector, int count);
/**
* 以格式方式异步向流中写数据, 当流出错、写超时或写成功时将触发事件通知过程
* @param astream {ACL_ASTREAM*} 处于写监控的流
* @param fmt {const char*} 格式字符串
* @param ap {va_list} 格式字符串的参数列表
*/
ACL_API void acl_aio_vfprintf(ACL_ASTREAM *astream, const char *fmt, va_list ap);
/**
* 以格式方式异步向流中写数据, 当流出错、写超时或写成功时将触发事件通知过程
* @param astream {ACL_ASTREAM*} 处于写监控的流
* @param fmt {const char*} 格式字符串
* @param ... 变参参数表
*/
ACL_API void ACL_PRINTF(2, 3) acl_aio_fprintf(ACL_ASTREAM *astream, const char *fmt, ...);
/**
* 设置异步流为写监听状态,当该流可写时则调用用户的回调函数
* @param astream {ACL_ASTREM*} 异步流对象
* @param can_write_fn {ACL_AIO_NOTIFY_FN} 用户回调函数
* @param context {void*} can_write_fn 的参数之一
*/
ACL_API void acl_aio_enable_write(ACL_ASTREAM *astream,
ACL_AIO_NOTIFY_FN can_write_fn, void *context);
/**
* 停止对一个数据流进行IO写操作
* @param astream {ACL_ASTREAM*} 异步数据流
*/
ACL_API void acl_aio_disable_write(ACL_ASTREAM *astream);
/**
* 判断流是否在异步事件的写监听集合中
* @param astream {ACL_ASTREAM*} 异步数据流
* @return {int} 0: 否,!= 0: 是
*/
ACL_API int acl_aio_iswset(ACL_ASTREAM *astream);
/*---------------------------- 异步监听操作接口 ------------------------------*/
/**
* 异步接收一个客户端连接流, 并将该客户端流回传给用户
* @param astream {ACL_ASTREAM*} 处于监听状态的流
*/
ACL_API void acl_aio_accept(ACL_ASTREAM *astream);
/**
* 异步监听, 当监听流上出错、超时或有新连接到达时将触发监听事件通知过程, 当有
* 新连接时用户需在自己的注册函数里 accept() 该新连接.
* @param astream {ACL_ASTREAM*} 处于监听状态的流
*/
ACL_API void acl_aio_listen(ACL_ASTREAM *astream);
/*---------------------------- 异步连接操作接口 ------------------------------*/
/**
* 异步连接一个远程服务器, 当连接流出错、超时或连接成功时将触发事件通知过程.
* @param aio {ACL_AIO*} 异步框架引擎句柄
* @param saddr {const char*} 远程服务器地址, 格式: ip:port, 如: 192.168.0.1:80
* @param timeout {int} 连接超时的时间值,单位为秒
* @return {ACL_ASTREAM*} 创建异步连接过程是否成功
*/
ACL_API ACL_ASTREAM *acl_aio_connect(ACL_AIO *aio, const char *addr, int timeout);
/*---------------------------- 其它通用异步操作接口 --------------------------*/
/**
* 停止对一个数据流进行IO读写操作
* @param astream {ACL_ASTREAM*} 异步数据流
*/
ACL_API void acl_aio_disable_readwrite(ACL_ASTREAM *astream);
/**
* 判断流是否在异步事件的读或写监听集合中
* @param astream {ACL_ASTREAM*} 异步数据流
* @return {int} 0: 否,!= 0: 是
*/
ACL_API int acl_aio_isset(ACL_ASTREAM *astream);
/**
* 获得当前异步流的引用计数值
* @param astream {ACL_ASTREAM*} 异步数据流
* @return {int} >=0异步流的引用计数值
*/
ACL_API int acl_aio_refer_value(ACL_ASTREAM * astream);
/**
* 将异步流的引用计数值加1
* @param astream {ACL_ASTREAM*} 异步数据流
*/
ACL_API void acl_aio_refer(ACL_ASTREAM *astream);
/**
* 将异步流的引用计数值减1
* @param astream {ACL_ASTREAM*} 异步数据流
*/
ACL_API void acl_aio_unrefer(ACL_ASTREAM *astream);
/**
* 添加一个定时器任务, 该函数仅是 acl_event_request_timer 的简单封装
* @param aio {ACL_AIO*} 异步通信引擎句柄
* @param timer_fn {ACL_EVENT_NOTIFY_TIME} 定时器任务回调函数.
* @param context {void*} timer_fn 的参数之一.
* @param idle_limit {acl_int64} 启动定时器函数的时间,单位为微秒.
* @param keep {int} 是否重复定时器任务
* @return {acl_int64} 剩余的时间, 单位为微秒.
*/
ACL_API acl_int64 acl_aio_request_timer(ACL_AIO *aio,
ACL_EVENT_NOTIFY_TIME timer_fn, void *context,
acl_int64 idle_limit, int keep);
/**
* 取消某个定时器任务, 该函数仅是 acl_event_cancel_timer 的简单封装.
* @param aio {ACL_AIO*} 异步通信引擎句柄
* @param timer_fn {ACL_EVENT_NOTIFY_TIME} 定时器任务回调函数.
* @param context {void*} timer_fn 的参数之一.
* @return {acl_int64} 剩余的时间, 单位为微秒.
*/
ACL_API acl_int64 acl_aio_cancel_timer(ACL_AIO *aio,
ACL_EVENT_NOTIFY_TIME timer_fn, void *context);
/**
* 设置是否需要循环启用通过 acl_aio_request_timer 设置的定时器任务
* @param aio {ACL_AIO*} 异步通信引擎句柄
* @param timer_fn {ACL_EVENT_NOTIFY_TIME} 定时器任务回调函数.
* @param context {void*} timer_fn 的参数之一.
* @param onoff {int} 是否重复定时器任务
*/
ACL_API void acl_aio_keep_timer(ACL_AIO *aio, ACL_EVENT_NOTIFY_TIME callback,
void *context, int onoff);
/**
* 判断所设置的定时器都处于重复使用状态
* @param aio {ACL_AIO*} 异步通信引擎句柄
* @param timer_fn {ACL_EVENT_NOTIFY_TIME} 定时器任务回调函数.
* @param context {void*} timer_fn 的参数之一.
* @return {int} !0 表示所设置的定时器都处于重复使用状态
*/
ACL_API int acl_aio_timer_ifkeep(ACL_AIO *aio, ACL_EVENT_NOTIFY_TIME callback,
void *context);
#ifdef __cplusplus
}
#endif
#endif