acl_ioctl.h 文件参考

#include "../stdlib/acl_define.h"
#include "../event/acl_events.h"
#include "../stdlib/acl_vstream.h"

acl_ioctl.h 的引用(Include)关系图:

此图展示该文件直接或间接的被哪些文件引用了:

浏览源代码.

宏定义
#define	ACL_IOCTL_CTL_END   0
#define	ACL_IOCTL_CTL_THREAD_MAX   1
#define	ACL_IOCTL_CTL_THREAD_IDLE   2
#define	ACL_IOCTL_CTL_DELAY_SEC   3
#define	ACL_IOCTL_CTL_DELAY_USEC   4
#define	ACL_IOCTL_CTL_INIT_FN   5
#define	ACL_IOCTL_CTL_EXIT_FN   6
#define	ACL_IOCTL_CTL_INIT_CTX   7
#define	ACL_IOCTL_CTL_EXIT_CTX   8
#define	ACL_IOCTL_CTL_THREAD_STACKSIZE   9

类型定义
typedef struct ACL_IOCTL	ACL_IOCTL
typedef void(*	ACL_IOCTL_NOTIFY_FN) (int event_type, ACL_IOCTL *ioc, ACL_VSTREAM *stream, void *context)
typedef void(*	ACL_IOCTL_WORKER_FN) (ACL_IOCTL *ioc, void *arg)
typedef void(*	ACL_IOCTL_THREAD_INIT_FN) (void *)
typedef void(*	ACL_IOCTL_THREAD_EXIT_FN) (void *)

函数
ACL_API ACL_IOCTL *	acl_ioctl_create (int max_threads, int idle_timeout)
ACL_API ACL_IOCTL *	acl_ioctl_create_ex (int event_mode, int max_threads, int idle_timeout, int delay_sec, int delay_usec)
ACL_API void	acl_ioctl_add_dog (ACL_IOCTL *ioc)
ACL_API void	acl_ioctl_ctl (ACL_IOCTL *ioc, int name,...)
ACL_API void	acl_ioctl_free (ACL_IOCTL *ioc)
ACL_API int	acl_ioctl_start (ACL_IOCTL *ioc)
ACL_API void	acl_ioctl_loop (ACL_IOCTL *ioc)
ACL_API ACL_EVENT *	acl_ioctl_event (ACL_IOCTL *ioc)
ACL_API void	acl_ioctl_disable_readwrite (ACL_IOCTL *ioc, ACL_VSTREAM *stream)
ACL_API void	acl_ioctl_disable_read (ACL_IOCTL *ioc, ACL_VSTREAM *stream)
ACL_API void	acl_ioctl_disable_write (ACL_IOCTL *ioc, ACL_VSTREAM *stream)
ACL_API int	acl_ioctl_isset (ACL_IOCTL *ioc, ACL_VSTREAM *stream)
ACL_API int	acl_ioctl_isrset (ACL_IOCTL *ioc, ACL_VSTREAM *stream)
ACL_API int	acl_ioctl_iswset (ACL_IOCTL *ioc, ACL_VSTREAM *stream)
ACL_API int	acl_ioctl_iocp_close (ACL_IOCTL *ioc, ACL_VSTREAM *stream)
ACL_API void	acl_ioctl_enable_read (ACL_IOCTL *ioc, ACL_VSTREAM *stream, int timeout, ACL_IOCTL_NOTIFY_FN callback, void *context)
ACL_API void	acl_ioctl_enable_write (ACL_IOCTL *ioc, ACL_VSTREAM *stream, int timeout, ACL_IOCTL_NOTIFY_FN callback, void *context)
ACL_API void	acl_ioctl_enable_connect (ACL_IOCTL *ioc, ACL_VSTREAM *stream, int timeout, ACL_IOCTL_NOTIFY_FN callback, void *context)
ACL_API void	acl_ioctl_enable_listen (ACL_IOCTL *ioc, ACL_VSTREAM *stream, int timeout, ACL_IOCTL_NOTIFY_FN callback, void *context)
ACL_API ACL_VSTREAM *	acl_ioctl_connect (const char *addr, int timeout)
ACL_API ACL_VSTREAM *	acl_ioctl_listen (const char *addr, int qlen)
ACL_API ACL_VSTREAM *	acl_ioctl_listen_ex (const char *addr, int qlen, int block_mode, int io_bufsize, int io_timeout)
ACL_API ACL_VSTREAM *	acl_ioctl_accept (ACL_VSTREAM *sstream, char *ipbuf, int size)
ACL_API acl_int64	acl_ioctl_request_timer (ACL_IOCTL *ioc, ACL_EVENT_NOTIFY_TIME timer_fn, void *context, acl_int64 idle_limit)
ACL_API acl_int64	acl_ioctl_cancel_timer (ACL_IOCTL *ioc, ACL_EVENT_NOTIFY_TIME timer_fn, void *context)
ACL_API int	acl_ioctl_add (ACL_IOCTL *ioc, ACL_IOCTL_WORKER_FN callback, void *arg)
ACL_API int	acl_ioctl_nworker (ACL_IOCTL *ioc)

宏定义说明

ACL_IOCTL_CTL_DELAY_SEC

#define ACL_IOCTL_CTL_DELAY_SEC   3

设置 select 时的秒级休息值

在文件 acl_ioctl.h 第 73 行定义.

ACL_IOCTL_CTL_DELAY_USEC

#define ACL_IOCTL_CTL_DELAY_USEC   4

设置 select 时的微秒级休息值

在文件 acl_ioctl.h 第 74 行定义.

ACL_IOCTL_CTL_END

#define ACL_IOCTL_CTL_END   0

控制结束标志

在文件 acl_ioctl.h 第 70 行定义.

ACL_IOCTL_CTL_EXIT_CTX

#define ACL_IOCTL_CTL_EXIT_CTX   8

设置线程退出时的回调参数

在文件 acl_ioctl.h 第 78 行定义.

ACL_IOCTL_CTL_EXIT_FN

#define ACL_IOCTL_CTL_EXIT_FN   6

设置线程退出时的线程退出回调函数

在文件 acl_ioctl.h 第 76 行定义.

ACL_IOCTL_CTL_INIT_CTX

#define ACL_IOCTL_CTL_INIT_CTX   7

设置线程初始化时的回调参数

在文件 acl_ioctl.h 第 77 行定义.

ACL_IOCTL_CTL_INIT_FN

#define ACL_IOCTL_CTL_INIT_FN   5

设置线程被创建时的线程初始化函数

在文件 acl_ioctl.h 第 75 行定义.

ACL_IOCTL_CTL_THREAD_IDLE

#define ACL_IOCTL_CTL_THREAD_IDLE   2

设置线程空闲退出时间

在文件 acl_ioctl.h 第 72 行定义.

ACL_IOCTL_CTL_THREAD_MAX

#define ACL_IOCTL_CTL_THREAD_MAX   1

设置最大线程数

在文件 acl_ioctl.h 第 71 行定义.

ACL_IOCTL_CTL_THREAD_STACKSIZE

#define ACL_IOCTL_CTL_THREAD_STACKSIZE   9

设置线程的规模尺寸大小(字节)

在文件 acl_ioctl.h 第 79 行定义.

类型定义说明

ACL_IOCTL

typedef struct ACL_IOCTL ACL_IOCTL

在文件 acl_ioctl.h 第 12 行定义.

ACL_IOCTL_NOTIFY_FN

typedef void(* ACL_IOCTL_NOTIFY_FN) (int event_type, ACL_IOCTL *ioc, ACL_VSTREAM *stream, void *context)

当数据流可用时的任务回调函数类型定义, 用户需要根据此函数原型实现自己的任务

参数

event_type	{int} 数据流的事件状态, 为下列状态之一: ACL_EVENT_READ: 数据流有数据可读; ACL_EVENT_WRITE: 数据流有空间可写; ACL_EVENT_RW_TIMEOUT: 该数据流读写超时; ACL_EVENT_XCPT: 数据流内部出现异常.
ioc	{ACL_IOCTL*} io 控制句柄
stream	{ACL_VSTREAM*} 网络流句柄
context	{void*} 用户自定义对象

在文件 acl_ioctl.h 第 25 行定义.

ACL_IOCTL_THREAD_EXIT_FN

typedef void(* ACL_IOCTL_THREAD_EXIT_FN) (void *)

在文件 acl_ioctl.h 第 30 行定义.

ACL_IOCTL_THREAD_INIT_FN

typedef void(* ACL_IOCTL_THREAD_INIT_FN) (void *)

在文件 acl_ioctl.h 第 29 行定义.

ACL_IOCTL_WORKER_FN

typedef void(* ACL_IOCTL_WORKER_FN) (ACL_IOCTL *ioc, void *arg)

在文件 acl_ioctl.h 第 28 行定义.

函数说明

acl_ioctl_accept()

ACL_API ACL_VSTREAM* acl_ioctl_accept	(	ACL_VSTREAM *	sstream,
		char *	ipbuf,
		int	size
	)

从监听套口获得一个客户端连接

参数

sstream	{ACL_VSTREAM*} 监听套字流
ipbuf	{char*} 客户端流的地址
size	{int} ipbuf 空间大小

返回

{ACL_VSTREAM*} 客户端连接流. != NULL 成功获得一个客户端连接的数据流; == NULL 可能被系统中断了一下, 调用者应忽略此情况

acl_ioctl_add()

ACL_API int acl_ioctl_add	(	ACL_IOCTL *	ioc,
		ACL_IOCTL_WORKER_FN	callback,
		void *	arg
	)

向当前线程池中增加一个新的任务

参数

ioc	{ACL_IOCTL*} 服务器任务池句柄
callback	{ACL_IOCTL_WORKER_FN} 工作任务的回调函数
arg	{void*} callback 的参数之一

返回

{int} 0: ok; < 0: error

acl_ioctl_add_dog()

ACL_API void acl_ioctl_add_dog

(

ACL_IOCTL *

ioc

)

为了防止在多线程模式下 select 等事件循环的时间等待，可以添加此项以中断等待， 加快事件循环过程

参数

ioc	{ACL_IOCTL*} 服务器任务池句柄

acl_ioctl_cancel_timer()

ACL_API acl_int64 acl_ioctl_cancel_timer	(	ACL_IOCTL *	ioc,
		ACL_EVENT_NOTIFY_TIME	timer_fn,
		void *	context
	)

取消某个定时器任务, 该函数仅是 acl_event_cancel_timer 的简单封装.

参数

ioc	{ACL_IOCTL*} 服务器任务池句柄
timer_fn	{ACL_EVENT_NOTIFY_TIME} 定时器任务回调函数.
context	{void*} timer_fn 的参数之一.

返回

{acl_int64} 剩余的时间, 单位为微秒.

acl_ioctl_connect()

ACL_API ACL_VSTREAM* acl_ioctl_connect	(	const char *	addr,
		int	timeout
	)

连接远程服务器

参数

addr	{const char*} 服务器端服务地址, 格式: ip:port, 如: 192.168.0.1:80
timeout	{int} 连接超时时间, 其含义如下: 1) 0: 非阻塞地连接远程服务器 2) -1: 阻塞地连接远程服务器直至连接成功或连接失败为止 3) > 0: 带超时地连接远程服务器

返回

{ACL_VSTREAM*} 客户端连接流. != NULL 表示连接成功或正在连接中; == NULL 连接失败或出错 注: 当处于上述情况 1) 时, 需要将返回的 ACL_VSTREAM 句柄置入可连接集合中通过回调 函数来对该流进行读写操作, 即还需要调用 acl_ioctl_enable_connect() 来确保连 接成功.

acl_ioctl_create()

ACL_API ACL_IOCTL* acl_ioctl_create	(	int	max_threads,
		int	idle_timeout
	)

创建一个服务器框架

参数

max_threads	{int} 所创建的任务池内的最大线程数
idle_timeout	{int} 每个线程空闲时间, 当某个纯种的空闲时间超过 此值时会自动退出, 单位为秒

返回

{ACL_IOCTL*} 服务器任务池句柄

acl_ioctl_create_ex()

ACL_API ACL_IOCTL* acl_ioctl_create_ex	(	int	event_mode,
		int	max_threads,
		int	idle_timeout,
		int	delay_sec,
		int	delay_usec
	)

创建一个服务器框架

参数

event_mode	{int} 事件方式: ACL_EVENT_SELECT/ACL_EVENT_KERNEL
max_threads	{int} 所创建的任务池内的最大线程数
idle_timeout	{int} 每个线程空闲时间, 当某个纯种的空闲时间超过 此值时会自动退出, 单位为秒
delay_sec	{int} 在事件循环中的秒值
delay_usec	{int} 在事件循环中的微秒值

返回

{ACL_IOCTL*} 服务器任务池句柄

acl_ioctl_ctl()

ACL_API void acl_ioctl_ctl	(	ACL_IOCTL *	ioc,
		int	name,
			...
	)

设置服务器任务池的控制参数

参数

ioc	{ACL_IOCTL*} 服务器任务池句柄
name	{int} 参数列表中的第一个参数, ACL_IOCTL_CTL_
...	变参参数序列

acl_ioctl_disable_read()

ACL_API void acl_ioctl_disable_read	(	ACL_IOCTL *	ioc,
		ACL_VSTREAM *	stream
	)

将数据流从事件的读监听中去除

参数

ioc	{ACL_IOCTL*} 服务器任务池句柄
stream	{ACL_VSTREAM*} 客户端数据流指针

acl_ioctl_disable_readwrite()

ACL_API void acl_ioctl_disable_readwrite	(	ACL_IOCTL *	ioc,
		ACL_VSTREAM *	stream
	)

将数据流从事件的读、写监听中去除

参数

ioc	{ACL_IOCTL*} 服务器任务池句柄
stream	{ACL_VSTREAM*} 客户端数据流指针

acl_ioctl_disable_write()

ACL_API void acl_ioctl_disable_write	(	ACL_IOCTL *	ioc,
		ACL_VSTREAM *	stream
	)

将数据流从事件的写监听中去除

参数

ioc	{ACL_IOCTL*} 服务器任务池句柄
stream	{ACL_VSTREAM*} 客户端数据流指针

acl_ioctl_enable_connect()

ACL_API void acl_ioctl_enable_connect	(	ACL_IOCTL *	ioc,
		ACL_VSTREAM *	stream,
		int	timeout,
		ACL_IOCTL_NOTIFY_FN	callback,
		void *	context
	)

异步地连接服务器, 连接成功或连接超时时后调用用户的回调函数

参数

ioc	{ACL_IOCTL*} 服务器任务池句柄
stream	{ACL_VSTREAM*} 处于连接远程服务器状态的本地客户端数据流
timeout	{int} 连接超时时间
callback	{ACL_IOCTL_NOTIFY_FN} 当数据流可写或出错或超时时的回调函数
context	{void*} 回调函数 callback 的参数之一, 主要用于传递用户自己的参数, 用户需要在 callback 内将该参数转换成自己的可识别类型

acl_ioctl_enable_listen()

ACL_API void acl_ioctl_enable_listen	(	ACL_IOCTL *	ioc,
		ACL_VSTREAM *	stream,
		int	timeout,
		ACL_IOCTL_NOTIFY_FN	callback,
		void *	context
	)

作为服务端来监听某个待监听地址

参数

ioc	{ACL_IOCTL*} 服务器任务池句柄
stream	{ACL_VSTREAM*} 处于连接远程服务器状态的本地客户端数据流
timeout	{int} 监听套接字监听超时时间, 当此超时时间到达且没有新连接到达时, 调用者可以在回调函数里处理其它事件, 如果该值为 0 则一直阻塞 到有新连接到达或出错时用户的回调函数才被调用
callback	{ACL_IOCTL_NOTIFY_FN} 当有新连接到达或监听套接字出错 或监听超时时的回调函数
context	{void*} callback 的参数之一, 参见上面说明

acl_ioctl_enable_read()

ACL_API void acl_ioctl_enable_read	(	ACL_IOCTL *	ioc,
		ACL_VSTREAM *	stream,
		int	timeout,
		ACL_IOCTL_NOTIFY_FN	callback,
		void *	context
	)

向任务池中添加一个读监听工作任务

参数

ioc	{ACL_IOCTL*} 服务器任务池句柄
stream	{ACL_VSTREAM*} 客户端数据流指针
timeout	{int} 流连接空闲超时时间
callback	{ACL_IOCTL_NOTIFY_FN} 当数据流可读或出错或超时时的回调函数
context	{void*} 回调函数 callback 的参数之一, 主要用于传递用户自己的参数, 用户需要在 callback 内将该参数转换成自己的可识别类型

acl_ioctl_enable_write()

ACL_API void acl_ioctl_enable_write	(	ACL_IOCTL *	ioc,
		ACL_VSTREAM *	stream,
		int	timeout,
		ACL_IOCTL_NOTIFY_FN	callback,
		void *	context
	)

向任务池中添加一个写监控工作任务

参数

ioc	{ACL_IOCTL*} 服务器任务池句柄
stream	{ACL_VSTREAM*} 客户端数据流指针
timeout	{int} 流连接空闲超时时间
callback	{ACL_IOCTL_NOTIFY_FN} 当数据流可写或出错或超时时的回调函数
context	{void*} 回调函数 callback 的参数之一, 主要用于传递用户自己的参数, 用户需要在 callback 内将该参数转换成自己的可识别类型

acl_ioctl_event()

ACL_API ACL_EVENT* acl_ioctl_event

(

ACL_IOCTL *

ioc

)

获得事件引擎句柄

参数

ioc	{ACL_IOCTL*} 服务器任务池句柄

返回

{ACL_EVENT*}

acl_ioctl_free()

ACL_API void acl_ioctl_free

(

ACL_IOCTL *

ioc

)

销毁任务池资源

参数

ioc	{ACL_IOCTL*} 服务器任务池句柄

acl_ioctl_iocp_close()

ACL_API int acl_ioctl_iocp_close	(	ACL_IOCTL *	ioc,
		ACL_VSTREAM *	stream
	)

设置流状, 当流的IO完成时自动关闭流

参数

ioc	{ACL_IOCTL*} 服务器任务池句柄
stream	{ACL_VSTREAM*} 客户端数据流指针

返回

{int} 是否真正被关闭 0: 表示流中还有数据未处理完, 将进入异步关闭过程; 1: 表示流中无未处理数据, 已经被同步关闭

acl_ioctl_isrset()

ACL_API int acl_ioctl_isrset	(	ACL_IOCTL *	ioc,
		ACL_VSTREAM *	stream
	)

判断某个流是否处理于读监控状态

参数

ioc	{ACL_IOCTL*} 服务器任务池句柄
stream	{ACL_VSTREAM*} 客户端数据流指针

返回

{int} 1：表示是; 0: 表示否

acl_ioctl_isset()

ACL_API int acl_ioctl_isset	(	ACL_IOCTL *	ioc,
		ACL_VSTREAM *	stream
	)

判断某个流是否处于受监控状态, 只要读或写任何一种状态均返回真

参数

ioc	{ACL_IOCTL*} 服务器任务池句柄
stream	{ACL_VSTREAM*} 客户端数据流指针

返回

{int} 1：表示是; 0: 表示否

acl_ioctl_iswset()

ACL_API int acl_ioctl_iswset	(	ACL_IOCTL *	ioc,
		ACL_VSTREAM *	stream
	)

判断某个流是否处于写受监控状态

参数

ioc	{ACL_IOCTL*} 服务器任务池句柄
stream	{ACL_VSTREAM*} 客户端数据流指针

返回

{int} 1：表示是; 0: 表示否

acl_ioctl_listen()

ACL_API ACL_VSTREAM* acl_ioctl_listen	(	const char *	addr,
		int	qlen
	)

创建一个监听套接字流

参数

addr	{const char*} 本地被监听的地址, 格式: ip:port, 如: 127.0.0.1:80
qlen	{int} 监听队列长度

返回

{ACL_VSTREAM*} 监听套接字数据流. != NULL ok; == NULL err. 注: 若要异步监听, 则可以调用 acl_ioctl_enable_listen() 来异步地 获得一个客户端连接

acl_ioctl_listen_ex()

ACL_API ACL_VSTREAM* acl_ioctl_listen_ex	(	const char *	addr,
		int	qlen,
		int	block_mode,
		int	io_bufsize,
		int	io_timeout
	)

创建一个监听套接字流

参数

addr	{const char*} 本地被监听的地址, 格式: ip:port, 如: 127.0.0.1:80
qlen	{int} 监听队列长度
block_mode	{int} 是否采用非阻塞模式, ACL_BLOCKING: 阻塞模式, ACL_NON_BLOCKING: 非阻塞模式
io_bufsize	{int} 获得客户端连接流的缓冲区大小(字节)
io_timeout	{int} 客户端流的读写超时时间(秒)

返回

{ACL_VSTREAM*} 监听套接字数据流. != NULL ok; == NULL err. 注: 若要异步监听, 则可以调用 acl_ioctl_enable_listen() 来异步地 获得一个客户端连接

acl_ioctl_loop()

ACL_API void acl_ioctl_loop

(

ACL_IOCTL *

ioc

)

消息循环(仅适用于单线程模式)

参数

ioc	{ACL_IOCTL*} 服务器任务池句柄

acl_ioctl_nworker()

ACL_API int acl_ioctl_nworker

(

ACL_IOCTL *

ioc

)

获得当前线程池中工作线程的数量.

参数

ioc	{ACL_IOCTL*} 服务器任务池句柄

返回

{int} 返回当前工作线程的数量 == -1: error; >= 0: ok.

acl_ioctl_request_timer()

ACL_API acl_int64 acl_ioctl_request_timer	(	ACL_IOCTL *	ioc,
		ACL_EVENT_NOTIFY_TIME	timer_fn,
		void *	context,
		acl_int64	idle_limit
	)

给任务工作池添加一个定时器任务, 该函数仅是 acl_event_request_timer 的简单封装.

参数

ioc	{ACL_IOCTL*} 服务器任务池句柄
timer_fn	{ACL_EVENT_NOTIFY_TIME} 定时器任务回调函数.
context	{void*} timer_fn 的参数之一.
idle_limit	{acl_int64} 启动定时器函数的时间(微秒级)

返回

{acl_int64} 剩余的时间, 单位为微秒.

acl_ioctl_start()

ACL_API int acl_ioctl_start

(

ACL_IOCTL *

ioc

)

启动任务工作池

参数

ioc	{ACL_IOCTL*} 服务器任务池句柄

返回

{int} 是否启动服务器任务池正常. 0: ok; < 0: err.