diff --git a/About.md b/About.md deleted file mode 100644 index 867bb757c..000000000 --- a/About.md +++ /dev/null @@ -1,68 +0,0 @@ -# 1. About Acl project -The Acl (Advanced C/C++ Library) project is powerful multi-platform network communication library and service framework, suppoting LINUX, WIN32, Solaris, FreeBSD, AndroidOS, iOS. Many applications written by Acl run on these devices with Linux, Windows, iPhone and Android and serve billions of users. There are some important modules in Acl project, including network communcation, server framework, application protocols, multiple coders, etc. The common protocols such as HTTP/SMTP/ICMP//MQTT/Redis/Memcached/Beanstalk/Handler Socket are implemented in Acl, and the codec library such as XML/JSON/MIME/BASE64/UUCODE/QPCODE/RFC2047/RFC1035, etc., are also included in Acl. Acl also provides unified abstract interface for popular databases such as Mysql, Postgresql, Sqlite. Using Acl library users can write database application more easily, quickly and safely. - -Architecture diagram: - ![Overall architecture diagram](res/img/architecture_en.png) - -# 2. The six most important modules -As a C/C++ foundation library, Acl provides many useful functions for users to develop applications, including six important modules: HTTP, MIME, Redis client, Database interface, Coroutine, and Server framework. - -## 2.1. Coroutine -The coroutine module in Acl can be used on multiple platforms, and there are many engineering practices in some important projects. -- Run on Linux, MacOS, Windows, iOS and Android -- Support x86, Arm architecture -- Support select/poll/epoll/kqueue/iocp/win32 GUI message -- The DNS protocol has been implemented in acl coroutine, so DNS API can also be used in coroutine model -- Hook system IO API on Unix and Windows - - Read API: read/readv/recv/recvfrom/recvmsg - - Write API: write/writev/send/sendto/sendmsg/sendfile64 - - Socket API: socket/listen/accept/connect/setsockopt - - event API: select/poll/epoll_create/epoll_ctl/epoll_wait - - DNS API: gethostbyname/gethostbyname_r/getaddrinfo/freeaddrinfo -- Support shared stack mode to minimize memory usage -- Synchronization primitive - - Coroutine mutex, semphore can be used between coroutines - - Coroutine event can be used between coroutines and threads -- More information see [Using acl fiber](lib_fiber/README_en.md) - -## 2.2. HTTP module -Supports HTTP/1.1, can be used in client and server sides. -- HttpServlet interface like Java(server side) -- Connection pool mode(client side) -- Chunked block transfer -- Gzip compression/decompression -- SSL encrypted -- Breakpoints transmission -- Setting/acquisition of cookies -- Session managment(server side) -- Websocket transmission -- HTTP MIME format -- Sync/Async mode -- ... - -## 2.3. Redis client -The redis client module in Acl is powerful, high-performance and easy to use. -- Support Bitmap/String/Hash/List/Set/Sorted Set/PubSub/HyperLogLog/Geo/Script/Stream/Server/Cluster/etc. -- Provides stl-like C++ interface for each redis command -- Communication in single, cluster or pipeline mode -- Connection pool be used in signle or cluster mode -- More information see [Using acl redis client](lib_acl_cpp/samples/redis/README.md) - -## 2.4. MQTT module - -## 2.5. Database module -The unified database interface in Acl is designed to easily and safely operate thease well-known open source databases such as Mysql, Postgresq and SQLite. The SQL codec is designed to escape the charactors to avoid the DB SQL attacks. When users use Acl to write database applications, Acl will dynamically load the dynamic libraries of Mysql, Postgresql or SQLite. The advantage of dynamic loading is that users who don't need the database functionality don't care about it at all. - -## 2.6. Server framework -The most important module in Acl is the server framework, which helps users quickly write back-end services, such as web services. Tools in app/wizard can help users generate one appropriate service code within several seconds. The server framework of Acl includes two parts, one is the services manager, the other is the service written by Acl service template. The services manager named acl_master in Acl comes from the famous Postfix, whose name is master, and acl_master has many extensions to master in order to be as one general services manager. There are six service templates in Acl that can be used to write application services, as below: -- **Process service:** One connection one process, the advantage is that the programming is simple, safe and stable, and the disadvantage is that the concurrency is too low; -- **Threads service:** Each process handles all client connections through a set of threads in the thread pool. The IO event trigger mode is used that a connection is bound to a thread only if it has readable data, and the thread will be released after processing the data. The service model's advantage is that it can handle a large number of client connections in one process with a small number of threads. Compare with the aio model, the programming is relatively simple; -- **Aio service:** Similar to nginx/squid/ircd, one thread can handle a large number of client connections in a non-blocking IO manner. The advantages of this model are high processing efficiency and low resource consumption, while the disadvantages are more complex programming; -- **Fiber service:** Although the non-blocking service model can obtain large concurrent processing capability, the programming complexity is high. The coroutine model combines the features of large concurrent processing and low programming complexity, enabling programmers to easily implement sequential IO programming; -- **UDP service:** The model is mainly a service model supporting UDP communication process; -- **Trigger service:** The model instance is mainly used to process the background service process of some scheduled tasks (similar to the system's crontab). - -# 3. The other basic modules - -## 3.1. MIME module -MIME(Multipurpose Internet Mail Extensions) format is widely used in email application. MIME format is too important that it can be used not only for email applications, but also for Web applications. MIME RFC such as RFC2045/RFC2047/RFC822 has been implemented in Acl. Acl has a MIME data stream parser that is indepedent of the IO model, so it can be used by synchronous or asynchronous IO programs. diff --git a/README.md b/README.md index 15f53f107..87c42d8ff 100644 --- a/README.md +++ b/README.md @@ -1,328 +1,157 @@ -# acl -- One advanced C/C++ library for Unix/Windows. - -[English](README_EN.md) - - -* [一、描述](#一描述) - * [1.1、库组成](#11库组成) - * [1.2、功能模块组成](#12功能模块组成) - * [1.2.1、网络通信库](#121网络通信库) - * [1.2.1.1、流处理模块](#1211流处理模块) - * [1.2.1.2、网络操作模块](#1212网络操作模块) - * [1.2.1.3、非阻塞网络流](#1213非阻塞网络流) - * [1.2.1.4、常见网络应用协议库](#1214常见网络应用协议库) - * [1.2.1.5、常见网络通信库](#1215常见网络通信库) - * [1.2.2、网络 IO 事件引擎](#122网络-io-事件引擎) - * [1.2.3、网络服务器框架](#123网络服务器框架) - * [1.2.3.1、进程模型](#1231进程模型) - * [1.2.3.2、线程模型](#1232线程模型) - * [1.2.3.3、非阻塞模型](#1233非阻塞模型) - * [1.2.3.4、协程模型](#1234协程模型) - * [1.2.3.5、UDP通信模型](#1235udp通信模型) - * [1.2.3.6、触发器模型](#1236触发器模型) - * [1.2.4、线程及线程池模块](#124线程及线程池模块) - * [1.2.5、HTTP 协议库](#125http-协议库) - * [1.2.5.1、客户端模式](#1251客户端模式) - * [1.2.5.2、服务端模式](服务端模式) - * [1.2.6、Redis 客户端库](#126redis-客户端库) - * [1.2.7、MQTT 协议库](#127mqtt-协议库) - * [1.2.8、MIME 协议库](#128mime-协议库) - * [1.2.9、网络协程库](#129网络协程库) - * [1.2.10、数据库相关](#1210数据库相关) - * [1.2.11、数字键的 K-V 磁盘存储模块（zdb）](#1211数字键的-k-v-磁盘存储模块zdb) - * [1.2.12、其它功能库](#1212其它功能库) - * [1.2.12.1、常用数据结构模块](#12121常用数据结构模块) - * [1.2.12.2、内存操作模块](#12122-内存操作模块) - * [1.2.12.3、常用字符串操作模块](#12123常用字符串操作模块) - * [1.2.12.4、文件目录模块](#12124文件目录模块) - * [1.2.12.5、读配置文件模块](#12125读配置文件模块) - * [1.2.12.6、文件队列处理库](#12126文件队列处理库) - * [1.2.12.7、json解析库](#12127json解析库) - * [1.2.12.8、xml解析库](#12128xml解析库) - * [1.2.12.9、常见编码库](#12129常见编码库) -* [二、平台支持及编译](#二平台支持及编译) -* [三、目录结构说明](#三目录结构说明) - * [3.1、lib_acl---基础 C 库](#31lib_acl) - * [3.2、lib_protocol---HTTP/SMTP/ICMP 协议 C 库](#32lib_protocol) - * [3.3、lib_acl_cpp---C++ 功能库](#33lib_acl_cpp) - * [3.4、lib_fiber---网络协程库](#34lib_fiber) - * [3.5、图例](#35图例) - * [3.6、acl 库中有大量示例可供参考，请参考：SAMPLES.md](#36acl-库中有大量示例可供参考请参考samplesmd) - * [3.7、acl 使用 FAQ](#37acl-使用-faq-参考-faqmd) -* [四、谁在使用acl](#四谁在使用acl) -* [五、使用许可](#五使用许可) -* [六、参考](#六参考) - - - -## 一、描述 -acl 工程是一个跨平台（支持LINUX，WIN32，Solaris，MacOS，FreeBSD）的网络通信库及服务器编程框架，同时提供更多的实用功能库。通过该库，用户可以非常容易地编写支持多种模式(多线程、多进程、非阻塞、触发器、UDP方式、协程方式)的服务器程序，WEB 应用程序，数据库应用程序。此外，该库还提供了常见应用的客户端通信库（如：HTTP、SMTP、ICMP、MQTT、Redis、Memcache、Beanstalk、Handler socket），常见流式编解码库：XML/JSON/MIME/BASE64/UUCODE/QPCODE/RFC2047 etc。 - -### 1.1、库组成 -本工程主要包含 4 个库及大量示例。4 个库的说明如下： -1. **lib_acl**: 该库是最基础的库，其它 3 个库均依赖于该库; 该库以 C 语言实现。 -2. **lib_protocol**: 该库主要实现了 http 协议及 icmp/ping 协议; 该库以 C 语言实现。 -3. **lib_acl_cpp**: 该库用 C++ 语言封装了 lib_acl/lib_protocol 两个库，同时增加了一些其它有价值的功能应用。 -4. **lib_fiber**: 该库为支持协程库，直接 hook 系统 read/write 等 API，与 epoll 配合支持高并发网络编程，有关协程更多内容参考 [README.md](lib_fiber/README.md)。 - -* 整体架构图 - ![整体架构图](res/img/architecture.png) - -### 1.2、功能模块组成 -#### 1.2.1、网络通信库 -##### 1.2.1.1、流处理模块 -该模块是整个 acl 网络通信最基础的流式通信模块，不仅支持网络流，同时还支持文件流，主要支持： -1. 按行读数据，兼容 win32 下的 \r\n，同时兼容 UNIX 下的 \n 的结束符 -2. 按行读数据但要求自动去掉尾部的 \n 或 \r\n -3. 以字符串为分隔符读取数据 -4. 读规定长度的数据 -5. 尝试性读一行数据或尝试性读规定长度数据 -6. 探测网络 IO 状态 -7. 写入一行数据 -8. 按格式符写入数据，类似于 fprintf -9. 文件流定位操作，类似于 fseek -10. 一次性写入一组数据，类似于 unix 下的 writev -11. 将文件截短，类似于 ftrunk -12. 获取文件大小 -13. 获得当前文件流指针位置，类似于 ftell -14. 获得文件尺寸 -15. 获得网络流的本地地址及远程地址 - -##### 1.2.1.2、网络操作模块 -该模块主要支持网络服务端监听（支持 TCP/UDP/UNIX 域套接口）、网络客户端连接（支持 TCP/UNIX 域套接口）、DNS 域名查询及结果缓存（支持调用系统 gethostbyname/getaddrinfo 函数和直接发送 DNS 协议两种方式）、套接口（socket）操作及取本机网卡等功能。 - -##### 1.2.1.3、非阻塞网络流 -支持非阻塞方式连接、读（按行读，规定长度读）、写（写行，写规定长度，写一组数据）等操作。 - -##### 1.2.1.4、常见网络应用协议库 -主要支持常见网络应用协议，诸如：HTTP、SMTP、MQTT、ICMP，其中 HTTP、MQTT、ICMP 两个模块实现了阻塞、非阻塞两种通信方式；此外，HTTP 协议在C++版的 lib_acl_cpp 中还支持服务端、客户端两种通信方式，当作为服务端使用时，支持类似于 JAVA HttpServlet 的接口使用方式，当作为客户端方式使用时，支持连接池与集群管理方式，该模块同时支持 cookie、session、HTTP MIME 文件上传、分块传输、字符集自动转换、自动解压缩、断点续传等丰富的功能。 - -##### 1.2.1.5、常见网络通信库 -支持 Redis、Memcached、MQTT、Beanstalk、Handler socket 客户端通信库，该通信库支持连接池方式。 - -#### 1.2.2、网络 IO 事件引擎 -支持 select(UNIX/LINUX/WIN32)、poll(UNIX/LINUX)、epoll(LINUX)、kqueue(BSD)、devpoll(solaris)、iocp(WIN32)、窗口消息(WIN32) 等系统事件引擎，同时支持 Reactor 及 Proactor 两种编程模型。 - -#### 1.2.3、网络服务器框架 -该模块是 acl 中最为重要的模块，提供了服务器编程中常用的基础设施，该服务器框架来源于著名的 Postfix，在其基础上进行了诸多扩展，有关 acl 服务器编程的更多内容介绍参见：[acl服务器编程](https://blog.csdn.net/zsxxsz/category_8736921.html?spm=1001.2014.3001.5482)。 -目前已经支持的主要服务模型有： - -##### 1.2.3.1、进程模型 -一个连接一个进程，这种模型的优点是编程简单、安全稳定，缺点是并发度不高； - -##### 1.2.3.2、线程模型 -每个子进程是由线程池中的一组线程处理所有的客户端连接，采用 IO 事件触发方式，只有当连接有数据可读时才会将连接与一个线程进行绑定，线程处理完后立即归还给线程池，这种模型的最大优点是可以用少量的线程便可以处理大量的客户端连接，而且编程比较简单（相对于非阻塞模型）； - -##### 1.2.3.3、非阻塞模型 -每个子进程是由一个单独的非阻塞线程组成，该线程采用完全非阻塞 IO 方式处理外来的大量客户端连接（类似于 nginx/squid/ircd），该模型的优点是处理效率高占用资源少，可以处理大量客户端连接，缺点是编程比较复杂； - -##### 1.2.3.4、协程模型 -虽然非阻塞服务模型可以获得大并发处理能力，但编程复杂度较高，协程模型综合了大并发的处理能力和较低的编程复杂度的特点，使编程人员可以顺序 IO 的编程方式简单实现业务逻辑; - -##### 1.2.3.5、UDP通信模型 -该模型主要为了支持 UDP 网络过程而增加的服务模型； - -##### 1.2.3.6、触发器模型 -该模型的实例主要用来处理一些定时任务的后台服务过程（类似于系统的 crontab）。 - -服务器框架中的子进程实用采用半驻留服务模型，支持子进程预启动机制、最大最小进程数控制、子进程异常报警、单一进程监听多个地址（可同时监听TCP/UDP套接字以及 UNIX 域套接字）、子进程安全控制、日志输出至 syslog-ng、多进程TCP连接均匀化；采用配置文件驱动方式，每个服务一个配置文件，方便进程管理及服务进程在线升级。 - -#### 1.2.4、线程及线程池模块 -提供了跨平台的支持 Posix 规范的线程接口（支持WIN32）；线程池模块通过多种措施最大程度地减少线程任务分配时的锁冲突（用在 acl 服务器框架中多进程多线程服务模型中）。 - -#### 1.2.5、HTTP 协议库 -提供了完整的 HTTP 协议实现，支持 HTTP/1.0、1.1 版本，更多内容介绍见：[Acl HTTP编程](https://blog.csdn.net/zsxxsz/category_8736920.html)。 - -##### 1.2.5.1、客户端模式 -1. 支持连接池方式; -2. 支持 chunked 块传输; -3. 支持压缩传输; -4. 支持 SSL 加密传输; -5. 支持断点续传; -6. 支持设置/获取 Cookies; -7. 支持 Websocket. - -##### 1.2.5.2、服务端模式 -1. 支持类似于 Java 的 HttpServlet 使用方式; -2. 支持 chunked 块传输; -3. 支持压缩传输; -4. 支持 SSL 加密传输; -5. 支持断点续传; -6. 支持设置/获取 Cookies; -7. 支持 HTTP MIME 格式; -8. 支持 Websocket. - -#### 1.2.6、Redis 客户端库 -1. 支持 redis 集群模式及非集群模式; -2. 支持连接池方式; -3. 按 redis 数据结构类型分成独立的 C++ 类; -4. 每个命令映射为 1 个至多个函数. -更多有关 Acl Redis 客户端库编程的内容参见：[Acl Redis 介绍](lib_acl_cpp/samples/redis/README.md), [Redis示例](https://blog.csdn.net/zsxxsz/category_8736931.html)。 - -#### 1.2.7、MQTT 协议库 -1. 支持 MQTT3.1.1 版本； -2. 支持流式 MQTT 协议解析及构建； -3. 可以用在客户端及服务端； -4. 支持阻塞通信模式及非阻塞通信模式。 -有关 Acl MQTT 编程使用示例参见：[Acl MQTT](lib_acl_cpp/samples/mqtt/README.md)。 - -#### 1.2.8、MIME 协议库 -1. 支持流式 MIME 数据解析; -2. 支持 MIME RFC2045，RFC2047，RFC822. - -#### 1.2.9、网络协程库 -直接 hook 系统底层 IO API，与 epoll 配合实现网络 IO 的高并发、高性能编程框架，通过该模块可以使一些原生的常见阻塞式网络库（如 mysql/redis/http 等客户端库）直接支持高并发网络操作；通过使用该模块，编程者采用顺序思维编程方式，在协程库内部将阻塞模式转为非阻塞模式，因而大大提高了网络并发能力及处理性能。 - -#### 1.2.10、数据库相关 -设计了统一的数据库操作接口及连接池处理方式，目前支持 sqlite/mysql/postgresql。 - -#### 1.2.11、数字键的 K-V 磁盘存储模块（zdb） -采取 KEY/VALUE 分块存储方式，因为 KEY 限定为数字类型，只需内存计算便可算出 KEY 的位置，KEY 中存放了 VALUE 的位置，所以对于任何的数据查询只需两次磁盘定位。（本人在和讯做流量统计存储时，使用该种方式替代了BSD、TC 等采用B树的 K-V 存储）。 - -#### 1.2.12、其它功能库 - -##### 1.2.12.1、常用数据结构模块 -该模块提供了常见的哈希表（及多种哈希算法）、动态数组、双向链表、平衡二叉树、队列、二分块查找树、256 叉匹配树等数组结构；提供了统一的数据结构遍历方法(采用 acl_foreach)。 - -##### 1.2.12.2、 内存操作模块 - -该模块提供三种内存池模型： -1. 基本的内存方式：内部封装了系统的 malloc/free API，提供了内存校验等安全措施；该方式同时提供外部注册接口，允许使用者注册自己的内存分配模型； -2. 内存片(slab) 方式：根据不同的尺寸大小分配多个定长内存链，可以有效地减少内存碎片，大大提升内存分配效率； -3. 内存链方式：将长度不一的小内存分配在一条内存页上，可以非常有效地使用内存，减少内存浪费。 - -##### 1.2.12.3、常用字符串操作模块 -支持字符串匹配查找、前(后)向比较、字符串分割、字符串大小写转换、H2B/B2H 转换、URL 编码/解码等功能。 - -##### 1.2.12.4、文件目录模块 -支持多级目录创建、多级目录扫描、文件句柄缓存等功能，同时在处理多级目录采用循环方式，避免了递归方式时可能的栈溢出的隐患。 - -##### 1.2.12.5、读配置文件模块 -支持读 name=value 形式的配置文件，value 较长时可以使用反斜杠(\)折行，采用配置表方式提取配置文件中的配置项。 - -##### 1.2.12.6、文件队列处理库 -支持多组目录队列文件的创建、扫描、删除等操作；常用于临时文件队列调度的服务程序中。 - -##### 1.2.12.7、json 解析库 -支持流式方式解析 json 数据，同时支持 json 数据包组装。 - -##### 1.2.12.8、xml 解析库 -支持流式方式解析 xml 数据，同时支持 xml 数据包组装。 - -##### 1.2.12.9、常见编码库 -还包括 rfc2047、url、base64、uucode、qpcode、charset 等编解码库，这些解码库均采用流式解析方式，适合于多种网络 IO 模型（阻塞/非阻塞TCP、UDP）。 - -## 二、平台支持及编译 -整个工程目前支持 Linux(AS4,5,6, CS4,5,6, ubuntu), Windows, MacOS, FreeBSD, Solaris，Android，IOS。 -* Linux/UNIX: 编译器为 gcc，直接在终端命令行方式下分别进入 lib_acl/lib_protocol/lib_acl_cpp 目录下，运行 make 命令即可。 -* Windows: 可以用 VC2003/VC2008/VC2010/VC2012/vc2013/vc2015/vc2017/vc2019 进行编译。 -* MacOS：可使用 xcode 进行编译。 -* 同时支持 CMake 跨平台编译方式 - -当在 WIN32 环境下使用动态库时有几点需要注意： -* 使用 lib_acl 的动态库时，需要在用户的工程预定义: ACL_DLL; -* 使用 lib_protocol 动态库中的 HTTP 库或 ICMP 库时，需要在工程中预定义 HTTP_DLL 或 ICMP_DLL; -* 使用 lib_acl_cpp 的动态库时，需要在工程中预定义 ACL_CPP_DLL，如果您使用用 VC2003 编译环境则还需要预定义 VC2003; -* 详细编译过程，参见：[acl 库的编译及使用](BUILD.md) - -## 三、目录结构说明 - -### 3.1、lib_acl -1. init : 主要用于初始化 acl 基础库 -2. stdlib : 是一些比较基础的功能函数库，在 stdlib/ 根目录下主要包括一些有关日志记录、网络/文件流处理、VSTRING缓冲操作等功能函数；在 stdlib/ 下还有二级目录，如下： -- 2.1 common : 该目录主要为一些常用的数据结构及算法的功能函数库，象哈希表、链表、队列、动态数组、堆栈、缓存、平衡二叉树、模式匹配树等； -- 2.2 memory : 该目录主要包含与内存操作相关的函数库，象内存基础分配与校验、内存池管理、内存切片管理等； -- 2.3 filedir : 该目录主要包含与目录遍历、目录创建等相关的库； -- 2.4 configure : 该目录主要包含配置文件的分析库； -- 2.5 iostuff : 该目录主要包含一些常用的IO操作的函数库，象读/写超时、设置IO句柄的阻塞模式等； -- 2.6 string : 该目录主要包含一些常用的字符串操作的库，提供了比标准C更灵活高效的字符串操作功能； -- 2.7 debug : 主要用于协助调试内存的泄露等功能； -- 2.8 sys : 主要是与不同操作系统平台相关的API的封装函数库； -3. **net: 是与网络操作相关的函数库，包含网络监听、网络连接、DNS查询、套接口参数设置等功能；** -- 3.1 connect : 主要是与网络连接相关的函数库，包含网络连接、域套接口连接等； -- 3.2 listen : 主要是与网络监听相关的函数库，包含网络监听、域套接口监听等； -- 3.3 dns : 主要是与DNS域名查询相关的函数库，包含对 gethostbyname 等接口的封装、按RFC1035标准直接发送UDP包方式进行查询等功能； -4. **event : 主要封装了 select/poll/epoll/iocp/win message/kqueue/devpoll 等系统API接口，使处理网络事件更加灵活、高效、简单，另外还包含定时器接口，acl 中的很多网络应用都会用到这些接口，象 aio、master 等模块；** -5. **aio : 主要包含网络异步操作的功能函数，该套函数库在处理高并发时有非常高的效率，而且提供了比基础API更为高级的调用方式，比使用象 libevent 之类的函数库更为简单，而且是线程安全的；** -6. msg : 主要包含了基于线程的消息事件及基于网络的消息事件功能； -7. thread : 主要是封装了各个OS平台下的基础线程API，使对外接口保持一致性，消除了平台的差异性，同时还提供了半驻留线程池的函数库，以及对于线程局部变量的扩展； -8. db : 主要是一些与数据库有关的功能库，定义了一个通用的数据库连接池的框架（并且实现了mysql的连接池实例）；一个简单的内存数据库（由哈希表、链表、平衡二叉树组合而成）；ZDB数据存储引擎，这是一个高效的基于数字键的存储引擎； -9. proctl : win32 平台下父子进程控制功能库； -10. code : 常见编码函数库，包括 base64编解码、URL编解码以及一些汉字字符集编码等； -11. unit_test : 包含有关进行 C 语言单元测试的功能库； -12. xml: 是一个流式的 xml 解析器及构造器，可以支持阻塞及阻塞式网络通信； -13. json: 是一个流式的 json 解析器及构造器，可以支持阻塞及阻塞式网络通信； -14. **master: 是在 UNIX 环境下支持多种服务器模式的服务器框架，目前主要支持多进程模式、多进程多线程模式、多进程非阻塞模式、多进程触发器模式及 UDP 通信模式；** - -### 3.2、lib_protocol -1. http: HTTP 协议相关的库，支持 HTTP/1.1，通讯方式支持同步/异步方式 -2. icmp: icmp/ping 协议库，支持同步/异步通信方式 -3. smtp: 邮件客户端发信协议库 - -### 3.3、lib_acl_cpp -1. stdlib: 主要包含字符串处理类(string)，xml/json 解析库，zlib 压缩库(依赖于 zlib 库), 日志记录类, 字符集转码(在UNIX环境下需要 iconv 库), memcached 客户库, 互斥类(支持线程锁、文件锁); -2. **stream: 支持网络流/文件流，支持阻塞/非阻塞两种通信方式，在非阻塞模式下支持 select/poll/epoll/iocp/win32 message/kqueue/devpoll；支持 ssl 加密传输(阻塞及非阻塞方式，需要 polarssl库);** -3. ipc: 在非阻塞通信方式，提供了阻塞模块与非阻塞模块整合的方式; -4. **http: 比较完整的 HTTP 通信库及协议解析库，支持客户端及服务端模式，支持 ssl/gzip 传输方式; 支持类似于 Java HttpServlet 方式的大部分接口，方便编写 CGI 及 WEB 服务器程序；** -5. db: 封装了 MYSQL/SQLITE 库，支持数据库连接池； -6. hsocket: 实现了完整的 handler-socket 客户端通信库； -7. **mime: 支持完整的与邮件编码相关的库(邮件的 rfc2045-rfc2047/rfc822/base64/uucode 编码及解码库).** -8. **master: 封装了 C 库的服务器框架库** -9. beanstalk: 消息队列应用 beanstalkd 的客户端通信库，支持连接池 -10. connpool: 通用的连接池库 -11. hscoket: mysql 插件 handle-socket 的客户端通信库，支持连接池 -12. memcache: memcached 应用的客户端库，支持连接池及连接池集群管理 -13. queue: 磁盘文件队列操作库 -14. ipc: 阻塞/非阻塞通信整合库 -15. session: HTTP 会话库 -16. **redis: 完整实现了 redis 协议的客户端通信库(总共 12 个大类，150 多个命令)，支持连接池及连接池集群管理** -17. disque: 支持集群消息队列服务 disque 的客户端库，支持连接池及连接池集群管理 -18. **mqtt: 支持流式解析 MQTT 协议，可以与任何 IO 通信方式结合；同时提供了阻塞及非阻塞通信接口** - -### 3.4、lib_fiber -1. c 目录：该目录下主要为 C 语言版本实现的网络协程库，其中包含源文件及头文件 -2. cpp 目录：该目录下封装了 C 语言版本的网络协程库 -3. samples 目录：该目录下有大量的使用协程库编程的例子 - -### 3.5、图例 -* 类索引图： - ![类索引图](res/img/index.jpg) -* 异步 IO 类继承图 - ![异步 IO 类继承图](res/img/aio_inherit.jpg) -* IO 流继承图 - ![IO 流继承图](res/img/stream_inherit.jpg) -* acl 服务框架守护进程事件处理流程 - ![acl 服务守护进程事件处理流程](res/img/acl_master.jpg) -* acl 服务器框架子进程事件处理流程 - ![服务子进程事件流程](res/img/master_proc.jpg) -* 接收上传文件的 CGI 程序： - ![接收上传文件的 CGI 程序](res/img/cgi_upload.jpg) -* 文件下载客户端程序： - ![文件下载客户端程序](res/img/http_download.jpg) -* 网页下载程序： - ![网页下载程序](res/img/http_client.jpg) - -### 3.6、acl 库中有大量示例可供参考，请参考：[SAMPLES.md](SAMPLES.md) -### 3.7、acl 使用 FAQ 参考 [FAQ.md](FAQ.md) - -## 四、谁在使用acl -[![iqiyi](res/logo/logo_iqiyi.png)](http://www.iqiyi.com/) -[![263](res/logo/logo_263.png)](http://www.263.net/) -[![hexun](res/logo/logo_hexun.png)](http://www.hexun.com/) -[![v1](res/logo/logo_v1.png)](http://www.v1.cn/) -[![lecloud](res/logo/logo_lecloud.png)](http://www.lecloud.com/) -[![ksyun](res/logo/logo_ksyun.png)](https://www.ksyun.com/) -[![weibangong](res/logo/logo_weibangong.png)](https://www.weibangong.com/) -[![xianyou](res/logo/logo_xianyou.png)](http://www.i3game.com/) -[![foundao](res/logo/logo_foundao.png)](http://www.foundao.com/) - -## 五、使用许可 -- LGPL-v3 license (see [LICENSE.txt](LICENSE.txt) in the acl project) - -## 六、参考 -- WEB 站点: https://blog.csdn.net/zsxxsz -- Github: https://github.com/acl-dev/acl -- Oschina: https://gitee.com/acl-dev/acl -- Download: https://sourceforge.net/projects/acl -- 微 博： http://weibo.com/zsxxsz -- QQ 群: 242722074(已满)，693868497 +[中文简体](README_CN.md) + +# Acl -- One Advanced C/C++ Library for Unix/Windows + +# 1. About Acl project +The Acl (Advanced C/C++ Library) project is powerful multi-platform network communication library and service framework, suppoting LINUX, WIN32, Solaris, FreeBSD, AndroidOS, iOS. Many applications written by Acl run on these devices with Linux, Windows, iPhone and Android and serve billions of users. There are some important modules in Acl project, including network communcation, server framework, application protocols, multiple coders, etc. The common protocols such as HTTP/SMTP/ICMP//MQTT/Redis/Memcached/Beanstalk/Handler Socket are implemented in Acl, and the codec library such as XML/JSON/MIME/BASE64/UUCODE/QPCODE/RFC2047/RFC1035, etc., are also included in Acl. Acl also provides unified abstract interface for popular databases such as Mysql, Postgresql, Sqlite. Using Acl library users can write database application more easily, quickly and safely. + +Architecture diagram: + ![Overall architecture diagram](res/img/architecture_en.png) + +# 2. The six most important modules +As a C/C++ foundation library, Acl provides many useful functions for users to develop applications, including six important modules: Network, Coroutine, HTTP, Redis client, MQTT, and Server framework. + +## 2.1. Basic network module +- Stream processing module +This module is the most basic streaming communication module for the entire acl network communication. It not only supports network streaming, but also supports file streaming. It mainly supports: + - Read data by line, compatible with \r\n under win32, and compatible with the end of \n under UNIX + - Read data by line but require automatic removal of the trailing \n or \r\n + - Read data as a string separator + - Read the specified length of data + - Try to read a row of data or try to read the specified length of data + - Detect network IO status + - Write a row of data + - Write data by formatter, similar to fprintf + - File stream location operation, similar to fseek + - Write a set of data at once, similar to writev under unix + - Truncate the file, similar to ftrunk + - Get the file size + - Get the current file stream pointer location, similar to ftell + - Get the file size + - Obtain the local address and remote address of the network stream + +- Network operation module + - This module mainly supports network server monitoring (supports TCP/UDP/UNIX domain socket), network client connection (supports TCP/UNIX domain socket), DNS domain name query and result cache (supports calling system gethostbyname/getaddrinfo function and direct Send DNS protocol two ways), socket (socket) operation and take the local network card and other functions. +- Non-blocking network flow + - Support non-blocking mode connection, read (by row read, specified length read), write (write line, write specified length, write a set of data) and other operations. + +- Common network application protocol library + - It mainly supports common network application protocols, such as: HTTP, SMTP, ICMP, in which HTTP and ICMP modules implement blocking and non-blocking communication methods. In addition, the HTTP protocol supports server and client in C++ version of lib_acl_cpp. Two communication methods, when used as a server, support the interface usage similar to JAVA HttpServlet. When used as a client mode, it supports connection pool and cluster management. The module supports both cookie, session, and HTTP MIME file upload. Rich functions such as block transfer, automatic character set conversion, automatic decompression, and breakpoint resume. + +- Common network communication library + - Support memcached, beanstalk, handler socket client communication library, the communication library supports connection pool mode. + +## 2.2. Coroutine +The coroutine module in Acl can be used on multiple platforms, and there are many engineering practices in some important projects. +- Run on Linux, MacOS, Windows, iOS and Android +- Support x86, Arm architecture +- Support select/poll/epoll/kqueue/iocp/win32 GUI message +- The DNS protocol has been implemented in acl coroutine, so DNS API can also be used in coroutine model +- Hook system IO API on Unix and Windows + - Read API: read/readv/recv/recvfrom/recvmsg + - Write API: write/writev/send/sendto/sendmsg/sendfile64 + - Socket API: socket/listen/accept/connect/setsockopt + - event API: select/poll/epoll_create/epoll_ctl/epoll_wait + - DNS API: gethostbyname/gethostbyname_r/getaddrinfo/freeaddrinfo +- Support shared stack mode to minimize memory usage +- Synchronization primitive + - Coroutine mutex, semphore can be used between coroutines + - Coroutine event can be used between coroutines and threads +- More information see [Using acl fiber](lib_fiber/README_en.md) + +## 2.3. HTTP module +Supports HTTP/1.1, can be used in client and server sides. +- HttpServlet interface like Java(server side) +- Connection pool mode(client side) +- Chunked block transfer +- Gzip compression/decompression +- SSL encrypted +- Breakpoints transmission +- Setting/acquisition of cookies +- Session managment(server side) +- Websocket transmission +- HTTP MIME format +- Sync/Async mode +- ... + +## 2.4. Redis client +The redis client module in Acl is powerful, high-performance and easy to use. +- Support Bitmap/String/Hash/List/Set/Sorted Set/PubSub/HyperLogLog/Geo/Script/Stream/Server/Cluster/etc. +- Provides stl-like C++ interface for each redis command +- Automaticaly cache and adapt the changing of hash slots of the redis cluster on the client +- Communication in single, cluster or pipeline mode +- Connection pool be used in signle or cluster mode +- High performance in cluster or pipline mode +- Same interface for single, cluster and pipeline modes +- Retry automatically for the reason of network error +- Can be used in the shared stack coroutine mode +- More information see [Using acl redis client](lib_acl_cpp/samples/redis/README.md) + +## 2.5. MQTT module +The MQTT 3.1.1 version has been implemented in Acl, which has a stream parser, so can be used indepedentily of any IO mode. +- Support MQTT 3.1.1 protocol: CONNECT/CONNACK/PUBLISH/PUBACK/PUBREC/PUBREL/PUBCOMP/SUBSCRIBE/SUBACK/UNSUBSCRIBE/UNSUBACK/PINGREQ/PINGRESP/DISCONNECT +- One class per command +- Stream parser can be used for any IO mode +- Data parsing separats from network communicationo +- Can be used on client and server sides + +## 2.6. Server framework +The most important module in Acl is the server framework, which helps users quickly write back-end services, such as web services. Tools in app/wizard can help users generate one appropriate service code within several seconds. The server framework of Acl includes two parts, one is the services manager, the other is the service written by Acl service template. The services manager named acl_master in Acl comes from the famous Postfix, whose name is master, and acl_master has many extensions to master in order to be as one general services manager. There are six service templates in Acl that can be used to write application services, as below: +- **Process service:** One connection one process, the advantage is that the programming is simple, safe and stable, and the disadvantage is that the concurrency is too low; +- **Threads service:** Each process handles all client connections through a set of threads in the thread pool. The IO event trigger mode is used that a connection is bound to a thread only if it has readable data, and the thread will be released after processing the data. The service model's advantage is that it can handle a large number of client connections in one process with a small number of threads. Compare with the aio model, the programming is relatively simple; +- **Aio service:** Similar to nginx/squid/ircd, one thread can handle a large number of client connections in a non-blocking IO manner. The advantages of this model are high processing efficiency and low resource consumption, while the disadvantages are more complex programming; +- **Fiber service:** Although the non-blocking service model can obtain large concurrent processing capability, the programming complexity is high. The coroutine model combines the features of large concurrent processing and low programming complexity, enabling programmers to easily implement sequential IO programming; +- **UDP service:** The model is mainly a service model supporting UDP communication process; +- **Trigger service:** The model instance is mainly used to process the background service process of some scheduled tasks (similar to the system's crontab). + +# 3. The other important modules + +## 3.1. MIME module +MIME(Multipurpose Internet Mail Extensions) format is widely used in email application. MIME format is too important that it can be used not only for email applications, but also for Web applications. MIME RFC such as RFC2045/RFC2047/RFC822 has been implemented in Acl. Acl has a MIME data stream parser that is indepedent of the IO model, so it can be used by synchronous or asynchronous IO programs. + +## 3.2. Codec module +Thare are some common codecs in Acl, such as Json, Xml, Base64, Url, etc., which are all stream parser and indepedent of IO communication. Json is very popular, so Acl also provides serialization/deserialization tools which can be used to transfer between Json data and C struct objects, which greatly improves the programming efficiency. + +## 3.3. Database module +The unified database interface in Acl is designed to easily and safely operate thease well-known open source databases such as Mysql, Postgresq and SQLite. The SQL codec is designed to escape the charactors to avoid the DB SQL attacks. When users use Acl to write database applications, Acl will dynamically load the dynamic libraries of Mysql, Postgresql or SQLite. The advantage of dynamic loading is that users who don't need the database functionality don't care about it at all. + +# 4. Platform support and compilation +Acl project currently supports Linux, Windows, MacOS, FreeBSD, Solaris, Android, IOS. +- Linux/UNIX: The compiler is gcc, enter the lib_acl/lib_protocol/lib_acl_cpp directory directly in the terminal command line mode, run the make command. +- Windows: Can be compiled with VS2003/VS2008/VS2010/VS2012/VS2013/VS2015/VS2019. (If you need to compile with VS6/VS2005, you can refer to the compilation conditions of VS2003). +- MacOS: Compiled with xcode. +- Support for CMake cross-platform compilation + +There are a few things to keep in mind when using dynamic libraries in a WIN32 environment: +- When using the dynamic library of lib_acl, it needs to be predefined in the user's project: ACL_DLL; +- When using the HTTP library or ICMP library in the lib_protocol dynamic library, you need to predefine HTTP_DLL or ICMP_DLL in the project; +- When using the dynamic library of lib_acl_cpp, you need to predefine ACL_CPP_DLL in the project. If you use the VC2003 compiler environment, you need to predefine VC2003. +- When using the dynamic library of lib_dict, you need to predefine DICT_DLL in the project; +- When using a dynamic library of lib_tls, you need to predefine TLS_DLL in your project. +- Detailed compilation process, see: [compilation and use of acl library] (BUILD.md) + +# 5. More about +## 5.1. There are a lot of examples in the acl library for reference, please refer to: [SAMPLES.md](SAMPLES.md) + +## 5.2. Acl using FAQ: [FAQ.md](FAQ.md) + +## 5.3. Who are using acl? +[![iqiyi](res/logo/logo_iqiyi.png)](http://www.iqiyi.com/) +[![263](res/logo/logo_263.png)](http://www.263.net/) +[![hexun](res/logo/logo_hexun.png)](http://www.hexun.com/) +[![v1](res/logo/logo_v1.png)](http://www.v1.cn/) +[![lecloud](res/logo/logo_lecloud.png)](http://www.lecloud.com/) +[![ksyun](res/logo/logo_ksyun.png)](https://www.ksyun.com/) +[![weibangong](res/logo/logo_weibangong.png)](https://www.weibangong.com/) +[![xianyou](res/logo/logo_xianyou.png)](http://www.i3game.com/) +[![foundao](res/logo/logo_foundao.png)](http://www.foundao.com/) + +## 5.4. License +- LGPL-v3 license (see [LICENSE.txt](LICENSE.txt) in the acl project) + +## 5.5. Reference +- WEB site: https://blog.csdn.net/zsxxsz +- Github: https://github.com/acl-dev/acl +- Oschina: https://gitee.com/acl-dev/acl +- Weibo: http://weibo.com/zsxxsz +- QQ Group: ，693868497 diff --git a/README_CN.md b/README_CN.md new file mode 100644 index 000000000..b802edf29 --- /dev/null +++ b/README_CN.md @@ -0,0 +1,327 @@ +# acl -- One advanced C/C++ library for Unix/Windows. + +[English](README.md) + + +* [一、描述](#一描述) + * [1.1、库组成](#11库组成) + * [1.2、功能模块组成](#12功能模块组成) + * [1.2.1、网络通信库](#121网络通信库) + * [1.2.1.1、流处理模块](#1211流处理模块) + * [1.2.1.2、网络操作模块](#1212网络操作模块) + * [1.2.1.3、非阻塞网络流](#1213非阻塞网络流) + * [1.2.1.4、常见网络应用协议库](#1214常见网络应用协议库) + * [1.2.1.5、常见网络通信库](#1215常见网络通信库) + * [1.2.2、网络 IO 事件引擎](#122网络-io-事件引擎) + * [1.2.3、网络服务器框架](#123网络服务器框架) + * [1.2.3.1、进程模型](#1231进程模型) + * [1.2.3.2、线程模型](#1232线程模型) + * [1.2.3.3、非阻塞模型](#1233非阻塞模型) + * [1.2.3.4、协程模型](#1234协程模型) + * [1.2.3.5、UDP通信模型](#1235udp通信模型) + * [1.2.3.6、触发器模型](#1236触发器模型) + * [1.2.4、线程及线程池模块](#124线程及线程池模块) + * [1.2.5、HTTP 协议库](#125http-协议库) + * [1.2.5.1、客户端模式](#1251客户端模式) + * [1.2.5.2、服务端模式](服务端模式) + * [1.2.6、Redis 客户端库](#126redis-客户端库) + * [1.2.7、MQTT 协议库](#127mqtt-协议库) + * [1.2.8、MIME 协议库](#128mime-协议库) + * [1.2.9、网络协程库](#129网络协程库) + * [1.2.10、数据库相关](#1210数据库相关) + * [1.2.11、数字键的 K-V 磁盘存储模块（zdb）](#1211数字键的-k-v-磁盘存储模块zdb) + * [1.2.12、其它功能库](#1212其它功能库) + * [1.2.12.1、常用数据结构模块](#12121常用数据结构模块) + * [1.2.12.2、内存操作模块](#12122-内存操作模块) + * [1.2.12.3、常用字符串操作模块](#12123常用字符串操作模块) + * [1.2.12.4、文件目录模块](#12124文件目录模块) + * [1.2.12.5、读配置文件模块](#12125读配置文件模块) + * [1.2.12.6、文件队列处理库](#12126文件队列处理库) + * [1.2.12.7、json解析库](#12127json解析库) + * [1.2.12.8、xml解析库](#12128xml解析库) + * [1.2.12.9、常见编码库](#12129常见编码库) +* [二、平台支持及编译](#二平台支持及编译) +* [三、目录结构说明](#三目录结构说明) + * [3.1、lib_acl---基础 C 库](#31lib_acl) + * [3.2、lib_protocol---HTTP/SMTP/ICMP 协议 C 库](#32lib_protocol) + * [3.3、lib_acl_cpp---C++ 功能库](#33lib_acl_cpp) + * [3.4、lib_fiber---网络协程库](#34lib_fiber) + * [3.5、图例](#35图例) + * [3.6、acl 库中有大量示例可供参考，请参考：SAMPLES.md](#36acl-库中有大量示例可供参考请参考samplesmd) + * [3.7、acl 使用 FAQ](#37acl-使用-faq-参考-faqmd) +* [四、谁在使用acl](#四谁在使用acl) +* [五、使用许可](#五使用许可) +* [六、参考](#六参考) + + + +## 一、描述 +acl 工程是一个跨平台（支持LINUX，WIN32，Solaris，MacOS，FreeBSD）的网络通信库及服务器编程框架，同时提供更多的实用功能库。通过该库，用户可以非常容易地编写支持多种模式(多线程、多进程、非阻塞、触发器、UDP方式、协程方式)的服务器程序，WEB 应用程序，数据库应用程序。此外，该库还提供了常见应用的客户端通信库（如：HTTP、SMTP、ICMP、MQTT、Redis、Memcache、Beanstalk、Handler socket），常见流式编解码库：XML/JSON/MIME/BASE64/UUCODE/QPCODE/RFC2047 etc。 + +### 1.1、库组成 +本工程主要包含 4 个库及大量示例。4 个库的说明如下： +1. **lib_acl**: 该库是最基础的库，其它 3 个库均依赖于该库; 该库以 C 语言实现。 +2. **lib_protocol**: 该库主要实现了 http 协议及 icmp/ping 协议; 该库以 C 语言实现。 +3. **lib_acl_cpp**: 该库用 C++ 语言封装了 lib_acl/lib_protocol 两个库，同时增加了一些其它有价值的功能应用。 +4. **lib_fiber**: 该库为支持协程库，直接 hook 系统 read/write 等 API，与 epoll 配合支持高并发网络编程，有关协程更多内容参考 [README.md](lib_fiber/README.md)。 + +* 整体架构图 + ![整体架构图](res/img/architecture.png) + +### 1.2、功能模块组成 +#### 1.2.1、网络通信库 +##### 1.2.1.1、流处理模块 +该模块是整个 acl 网络通信最基础的流式通信模块，不仅支持网络流，同时还支持文件流，主要支持： +1. 按行读数据，兼容 win32 下的 \r\n，同时兼容 UNIX 下的 \n 的结束符 +2. 按行读数据但要求自动去掉尾部的 \n 或 \r\n +3. 以字符串为分隔符读取数据 +4. 读规定长度的数据 +5. 尝试性读一行数据或尝试性读规定长度数据 +6. 探测网络 IO 状态 +7. 写入一行数据 +8. 按格式符写入数据，类似于 fprintf +9. 文件流定位操作，类似于 fseek +10. 一次性写入一组数据，类似于 unix 下的 writev +11. 将文件截短，类似于 ftrunk +12. 获取文件大小 +13. 获得当前文件流指针位置，类似于 ftell +14. 获得文件尺寸 +15. 获得网络流的本地地址及远程地址 + +##### 1.2.1.2、网络操作模块 +该模块主要支持网络服务端监听（支持 TCP/UDP/UNIX 域套接口）、网络客户端连接（支持 TCP/UNIX 域套接口）、DNS 域名查询及结果缓存（支持调用系统 gethostbyname/getaddrinfo 函数和直接发送 DNS 协议两种方式）、套接口（socket）操作及取本机网卡等功能。 + +##### 1.2.1.3、非阻塞网络流 +支持非阻塞方式连接、读（按行读，规定长度读）、写（写行，写规定长度，写一组数据）等操作。 + +##### 1.2.1.4、常见网络应用协议库 +主要支持常见网络应用协议，诸如：HTTP、SMTP、MQTT、ICMP，其中 HTTP、MQTT、ICMP 两个模块实现了阻塞、非阻塞两种通信方式；此外，HTTP 协议在C++版的 lib_acl_cpp 中还支持服务端、客户端两种通信方式，当作为服务端使用时，支持类似于 JAVA HttpServlet 的接口使用方式，当作为客户端方式使用时，支持连接池与集群管理方式，该模块同时支持 cookie、session、HTTP MIME 文件上传、分块传输、字符集自动转换、自动解压缩、断点续传等丰富的功能。 + +##### 1.2.1.5、常见网络通信库 +支持 Redis、Memcached、MQTT、Beanstalk、Handler socket 客户端通信库，该通信库支持连接池方式。 + +#### 1.2.2、网络 IO 事件引擎 +支持 select(UNIX/LINUX/WIN32)、poll(UNIX/LINUX)、epoll(LINUX)、kqueue(BSD)、devpoll(solaris)、iocp(WIN32)、窗口消息(WIN32) 等系统事件引擎，同时支持 Reactor 及 Proactor 两种编程模型。 + +#### 1.2.3、网络服务器框架 +该模块是 acl 中最为重要的模块，提供了服务器编程中常用的基础设施，该服务器框架来源于著名的 Postfix，在其基础上进行了诸多扩展，有关 acl 服务器编程的更多内容介绍参见：[acl服务器编程](https://blog.csdn.net/zsxxsz/category_8736921.html?spm=1001.2014.3001.5482)。 +目前已经支持的主要服务模型有： + +##### 1.2.3.1、进程模型 +一个连接一个进程，这种模型的优点是编程简单、安全稳定，缺点是并发度不高； + +##### 1.2.3.2、线程模型 +每个子进程是由线程池中的一组线程处理所有的客户端连接，采用 IO 事件触发方式，只有当连接有数据可读时才会将连接与一个线程进行绑定，线程处理完后立即归还给线程池，这种模型的最大优点是可以用少量的线程便可以处理大量的客户端连接，而且编程比较简单（相对于非阻塞模型）； + +##### 1.2.3.3、非阻塞模型 +每个子进程是由一个单独的非阻塞线程组成，该线程采用完全非阻塞 IO 方式处理外来的大量客户端连接（类似于 nginx/squid/ircd），该模型的优点是处理效率高占用资源少，可以处理大量客户端连接，缺点是编程比较复杂； + +##### 1.2.3.4、协程模型 +虽然非阻塞服务模型可以获得大并发处理能力，但编程复杂度较高，协程模型综合了大并发的处理能力和较低的编程复杂度的特点，使编程人员可以顺序 IO 的编程方式简单实现业务逻辑; + +##### 1.2.3.5、UDP通信模型 +该模型主要为了支持 UDP 网络过程而增加的服务模型； + +##### 1.2.3.6、触发器模型 +该模型的实例主要用来处理一些定时任务的后台服务过程（类似于系统的 crontab）。 + +服务器框架中的子进程实用采用半驻留服务模型，支持子进程预启动机制、最大最小进程数控制、子进程异常报警、单一进程监听多个地址（可同时监听TCP/UDP套接字以及 UNIX 域套接字）、子进程安全控制、日志输出至 syslog-ng、多进程TCP连接均匀化；采用配置文件驱动方式，每个服务一个配置文件，方便进程管理及服务进程在线升级。 + +#### 1.2.4、线程及线程池模块 +提供了跨平台的支持 Posix 规范的线程接口（支持WIN32）；线程池模块通过多种措施最大程度地减少线程任务分配时的锁冲突（用在 acl 服务器框架中多进程多线程服务模型中）。 + +#### 1.2.5、HTTP 协议库 +提供了完整的 HTTP 协议实现，支持 HTTP/1.0、1.1 版本，更多内容介绍见：[Acl HTTP编程](https://blog.csdn.net/zsxxsz/category_8736920.html)。 + +##### 1.2.5.1、客户端模式 +1. 支持连接池方式; +2. 支持 chunked 块传输; +3. 支持压缩传输; +4. 支持 SSL 加密传输; +5. 支持断点续传; +6. 支持设置/获取 Cookies; +7. 支持 Websocket. + +##### 1.2.5.2、服务端模式 +1. 支持类似于 Java 的 HttpServlet 使用方式; +2. 支持 chunked 块传输; +3. 支持压缩传输; +4. 支持 SSL 加密传输; +5. 支持断点续传; +6. 支持设置/获取 Cookies; +7. 支持 HTTP MIME 格式; +8. 支持 Websocket. + +#### 1.2.6、Redis 客户端库 +1. 支持 redis 集群模式及非集群模式; +2. 支持连接池方式; +3. 按 redis 数据结构类型分成独立的 C++ 类; +4. 每个命令映射为 1 个至多个函数. +更多有关 Acl Redis 客户端库编程的内容参见：[Acl Redis 介绍](lib_acl_cpp/samples/redis/README.md), [Redis示例](https://blog.csdn.net/zsxxsz/category_8736931.html)。 + +#### 1.2.7、MQTT 协议库 +1. 支持 MQTT3.1.1 版本； +2. 支持流式 MQTT 协议解析及构建； +3. 可以用在客户端及服务端； +4. 支持阻塞通信模式及非阻塞通信模式。 +有关 Acl MQTT 编程使用示例参见：[Acl MQTT](lib_acl_cpp/samples/mqtt/README.md)。 + +#### 1.2.8、MIME 协议库 +1. 支持流式 MIME 数据解析; +2. 支持 MIME RFC2045，RFC2047，RFC822. + +#### 1.2.9、网络协程库 +直接 hook 系统底层 IO API，与 epoll 配合实现网络 IO 的高并发、高性能编程框架，通过该模块可以使一些原生的常见阻塞式网络库（如 mysql/redis/http 等客户端库）直接支持高并发网络操作；通过使用该模块，编程者采用顺序思维编程方式，在协程库内部将阻塞模式转为非阻塞模式，因而大大提高了网络并发能力及处理性能。 + +#### 1.2.10、数据库相关 +设计了统一的数据库操作接口及连接池处理方式，目前支持 sqlite/mysql/postgresql。 + +#### 1.2.11、数字键的 K-V 磁盘存储模块（zdb） +采取 KEY/VALUE 分块存储方式，因为 KEY 限定为数字类型，只需内存计算便可算出 KEY 的位置，KEY 中存放了 VALUE 的位置，所以对于任何的数据查询只需两次磁盘定位。（本人在和讯做流量统计存储时，使用该种方式替代了BSD、TC 等采用B树的 K-V 存储）。 + +#### 1.2.12、其它功能库 + +##### 1.2.12.1、常用数据结构模块 +该模块提供了常见的哈希表（及多种哈希算法）、动态数组、双向链表、平衡二叉树、队列、二分块查找树、256 叉匹配树等数组结构；提供了统一的数据结构遍历方法(采用 acl_foreach)。 + +##### 1.2.12.2、 内存操作模块 + +该模块提供三种内存池模型： +1. 基本的内存方式：内部封装了系统的 malloc/free API，提供了内存校验等安全措施；该方式同时提供外部注册接口，允许使用者注册自己的内存分配模型； +2. 内存片(slab) 方式：根据不同的尺寸大小分配多个定长内存链，可以有效地减少内存碎片，大大提升内存分配效率； +3. 内存链方式：将长度不一的小内存分配在一条内存页上，可以非常有效地使用内存，减少内存浪费。 + +##### 1.2.12.3、常用字符串操作模块 +支持字符串匹配查找、前(后)向比较、字符串分割、字符串大小写转换、H2B/B2H 转换、URL 编码/解码等功能。 + +##### 1.2.12.4、文件目录模块 +支持多级目录创建、多级目录扫描、文件句柄缓存等功能，同时在处理多级目录采用循环方式，避免了递归方式时可能的栈溢出的隐患。 + +##### 1.2.12.5、读配置文件模块 +支持读 name=value 形式的配置文件，value 较长时可以使用反斜杠(\)折行，采用配置表方式提取配置文件中的配置项。 + +##### 1.2.12.6、文件队列处理库 +支持多组目录队列文件的创建、扫描、删除等操作；常用于临时文件队列调度的服务程序中。 + +##### 1.2.12.7、json 解析库 +支持流式方式解析 json 数据，同时支持 json 数据包组装。 + +##### 1.2.12.8、xml 解析库 +支持流式方式解析 xml 数据，同时支持 xml 数据包组装。 + +##### 1.2.12.9、常见编码库 +还包括 rfc2047、url、base64、uucode、qpcode、charset 等编解码库，这些解码库均采用流式解析方式，适合于多种网络 IO 模型（阻塞/非阻塞TCP、UDP）。 + +## 二、平台支持及编译 +整个工程目前支持 Linux(AS4,5,6, CS4,5,6, ubuntu), Windows, MacOS, FreeBSD, Solaris，Android，IOS。 +* Linux/UNIX: 编译器为 gcc，直接在终端命令行方式下分别进入 lib_acl/lib_protocol/lib_acl_cpp 目录下，运行 make 命令即可。 +* Windows: 可以用 VC2003/VC2008/VC2010/VC2012/vc2013/vc2015/vc2017/vc2019 进行编译。 +* MacOS：可使用 xcode 进行编译。 +* 同时支持 CMake 跨平台编译方式 + +当在 WIN32 环境下使用动态库时有几点需要注意： +* 使用 lib_acl 的动态库时，需要在用户的工程预定义: ACL_DLL; +* 使用 lib_protocol 动态库中的 HTTP 库或 ICMP 库时，需要在工程中预定义 HTTP_DLL 或 ICMP_DLL; +* 使用 lib_acl_cpp 的动态库时，需要在工程中预定义 ACL_CPP_DLL，如果您使用用 VC2003 编译环境则还需要预定义 VC2003; +* 详细编译过程，参见：[acl 库的编译及使用](BUILD.md) + +## 三、目录结构说明 + +### 3.1、lib_acl +1. init : 主要用于初始化 acl 基础库 +2. stdlib : 是一些比较基础的功能函数库，在 stdlib/ 根目录下主要包括一些有关日志记录、网络/文件流处理、VSTRING缓冲操作等功能函数；在 stdlib/ 下还有二级目录，如下： +- 2.1 common : 该目录主要为一些常用的数据结构及算法的功能函数库，象哈希表、链表、队列、动态数组、堆栈、缓存、平衡二叉树、模式匹配树等； +- 2.2 memory : 该目录主要包含与内存操作相关的函数库，象内存基础分配与校验、内存池管理、内存切片管理等； +- 2.3 filedir : 该目录主要包含与目录遍历、目录创建等相关的库； +- 2.4 configure : 该目录主要包含配置文件的分析库； +- 2.5 iostuff : 该目录主要包含一些常用的IO操作的函数库，象读/写超时、设置IO句柄的阻塞模式等； +- 2.6 string : 该目录主要包含一些常用的字符串操作的库，提供了比标准C更灵活高效的字符串操作功能； +- 2.7 debug : 主要用于协助调试内存的泄露等功能； +- 2.8 sys : 主要是与不同操作系统平台相关的API的封装函数库； +3. **net: 是与网络操作相关的函数库，包含网络监听、网络连接、DNS查询、套接口参数设置等功能；** +- 3.1 connect : 主要是与网络连接相关的函数库，包含网络连接、域套接口连接等； +- 3.2 listen : 主要是与网络监听相关的函数库，包含网络监听、域套接口监听等； +- 3.3 dns : 主要是与DNS域名查询相关的函数库，包含对 gethostbyname 等接口的封装、按RFC1035标准直接发送UDP包方式进行查询等功能； +4. **event : 主要封装了 select/poll/epoll/iocp/win message/kqueue/devpoll 等系统API接口，使处理网络事件更加灵活、高效、简单，另外还包含定时器接口，acl 中的很多网络应用都会用到这些接口，象 aio、master 等模块；** +5. **aio : 主要包含网络异步操作的功能函数，该套函数库在处理高并发时有非常高的效率，而且提供了比基础API更为高级的调用方式，比使用象 libevent 之类的函数库更为简单，而且是线程安全的；** +6. msg : 主要包含了基于线程的消息事件及基于网络的消息事件功能； +7. thread : 主要是封装了各个OS平台下的基础线程API，使对外接口保持一致性，消除了平台的差异性，同时还提供了半驻留线程池的函数库，以及对于线程局部变量的扩展； +8. db : 主要是一些与数据库有关的功能库，定义了一个通用的数据库连接池的框架（并且实现了mysql的连接池实例）；一个简单的内存数据库（由哈希表、链表、平衡二叉树组合而成）；ZDB数据存储引擎，这是一个高效的基于数字键的存储引擎； +9. proctl : win32 平台下父子进程控制功能库； +10. code : 常见编码函数库，包括 base64编解码、URL编解码以及一些汉字字符集编码等； +11. unit_test : 包含有关进行 C 语言单元测试的功能库； +12. xml: 是一个流式的 xml 解析器及构造器，可以支持阻塞及阻塞式网络通信； +13. json: 是一个流式的 json 解析器及构造器，可以支持阻塞及阻塞式网络通信； +14. **master: 是在 UNIX 环境下支持多种服务器模式的服务器框架，目前主要支持多进程模式、多进程多线程模式、多进程非阻塞模式、多进程触发器模式及 UDP 通信模式；** + +### 3.2、lib_protocol +1. http: HTTP 协议相关的库，支持 HTTP/1.1，通讯方式支持同步/异步方式 +2. icmp: icmp/ping 协议库，支持同步/异步通信方式 +3. smtp: 邮件客户端发信协议库 + +### 3.3、lib_acl_cpp +1. stdlib: 主要包含字符串处理类(string)，xml/json 解析库，zlib 压缩库(依赖于 zlib 库), 日志记录类, 字符集转码(在UNIX环境下需要 iconv 库), memcached 客户库, 互斥类(支持线程锁、文件锁); +2. **stream: 支持网络流/文件流，支持阻塞/非阻塞两种通信方式，在非阻塞模式下支持 select/poll/epoll/iocp/win32 message/kqueue/devpoll；支持 ssl 加密传输(阻塞及非阻塞方式，需要 polarssl库);** +3. ipc: 在非阻塞通信方式，提供了阻塞模块与非阻塞模块整合的方式; +4. **http: 比较完整的 HTTP 通信库及协议解析库，支持客户端及服务端模式，支持 ssl/gzip 传输方式; 支持类似于 Java HttpServlet 方式的大部分接口，方便编写 CGI 及 WEB 服务器程序；** +5. db: 封装了 MYSQL/SQLITE 库，支持数据库连接池； +6. hsocket: 实现了完整的 handler-socket 客户端通信库； +7. **mime: 支持完整的与邮件编码相关的库(邮件的 rfc2045-rfc2047/rfc822/base64/uucode 编码及解码库).** +8. **master: 封装了 C 库的服务器框架库** +9. beanstalk: 消息队列应用 beanstalkd 的客户端通信库，支持连接池 +10. connpool: 通用的连接池库 +11. hscoket: mysql 插件 handle-socket 的客户端通信库，支持连接池 +12. memcache: memcached 应用的客户端库，支持连接池及连接池集群管理 +13. queue: 磁盘文件队列操作库 +14. ipc: 阻塞/非阻塞通信整合库 +15. session: HTTP 会话库 +16. **redis: 完整实现了 redis 协议的客户端通信库(总共 12 个大类，150 多个命令)，支持连接池及连接池集群管理** +17. disque: 支持集群消息队列服务 disque 的客户端库，支持连接池及连接池集群管理 +18. **mqtt: 支持流式解析 MQTT 协议，可以与任何 IO 通信方式结合；同时提供了阻塞及非阻塞通信接口** + +### 3.4、lib_fiber +1. c 目录：该目录下主要为 C 语言版本实现的网络协程库，其中包含源文件及头文件 +2. cpp 目录：该目录下封装了 C 语言版本的网络协程库 +3. samples 目录：该目录下有大量的使用协程库编程的例子 + +### 3.5、图例 +* 类索引图： + ![类索引图](res/img/index.jpg) +* 异步 IO 类继承图 + ![异步 IO 类继承图](res/img/aio_inherit.jpg) +* IO 流继承图 + ![IO 流继承图](res/img/stream_inherit.jpg) +* acl 服务框架守护进程事件处理流程 + ![acl 服务守护进程事件处理流程](res/img/acl_master.jpg) +* acl 服务器框架子进程事件处理流程 + ![服务子进程事件流程](res/img/master_proc.jpg) +* 接收上传文件的 CGI 程序： + ![接收上传文件的 CGI 程序](res/img/cgi_upload.jpg) +* 文件下载客户端程序： + ![文件下载客户端程序](res/img/http_download.jpg) +* 网页下载程序： + ![网页下载程序](res/img/http_client.jpg) + +### 3.6、acl 库中有大量示例可供参考，请参考：[SAMPLES.md](SAMPLES.md) +### 3.7、acl 使用 FAQ 参考 [FAQ.md](FAQ.md) + +## 四、谁在使用acl +[![iqiyi](res/logo/logo_iqiyi.png)](http://www.iqiyi.com/) +[![263](res/logo/logo_263.png)](http://www.263.net/) +[![hexun](res/logo/logo_hexun.png)](http://www.hexun.com/) +[![v1](res/logo/logo_v1.png)](http://www.v1.cn/) +[![lecloud](res/logo/logo_lecloud.png)](http://www.lecloud.com/) +[![ksyun](res/logo/logo_ksyun.png)](https://www.ksyun.com/) +[![weibangong](res/logo/logo_weibangong.png)](https://www.weibangong.com/) +[![xianyou](res/logo/logo_xianyou.png)](http://www.i3game.com/) +[![foundao](res/logo/logo_foundao.png)](http://www.foundao.com/) + +## 五、使用许可 +- LGPL-v3 license (see [LICENSE.txt](LICENSE.txt) in the acl project) + +## 六、参考 +- WEB 站点: https://blog.csdn.net/zsxxsz +- Github: https://github.com/acl-dev/acl +- Oschina: https://gitee.com/acl-dev/acl +- Download: https://sourceforge.net/projects/acl- 微 博： http://weibo.com/zsxxsz +- QQ 群: 693868497 diff --git a/README_EN.md b/README_EN_OLD.md similarity index 99% rename from README_EN.md rename to README_EN_OLD.md index 78f62fa95..b2d2615fa 100644 --- a/README_EN.md +++ b/README_EN_OLD.md @@ -315,6 +315,5 @@ There are a few things to keep in mind when using dynamic libraries in a WIN32 e - WEB site: https://blog.csdn.net/zsxxsz - Github: https://github.com/acl-dev/acl - Oschina: https://gitee.com/acl-dev/acl -- Download: https://sourceforge.net/projects/acl - Weibo: http://weibo.com/zsxxsz -- QQ Group: 242722074 +- QQ Group: 693868497