中文

Acl -- Advanced Cross-Platform C/C++ Network Communication Library and Server Framework

0. About Acl Project

Acl (Advanced C/C++ Library) is a powerful cross-platform network communication library and server programming framework that supports Linux, Windows, Solaris, FreeBSD, macOS, Android, iOS, and HarmonyOS. Numerous applications developed with Acl run on various devices, providing stable and reliable services to hundreds of millions of users.

The Acl project includes a rich set of functional modules: network communication, server framework, application protocols, various codecs, and more. It has built-in implementations of common network protocols such as HTTP/SMTP/ICMP/MQTT/Redis/Memcached/Beanstalk/Handler Socket, as well as complete codec libraries including XML/JSON/MIME/BASE64/UUCODE/QPCODE/RFC2047/RFC1035, etc. Additionally, Acl provides a unified abstract interface for mainstream databases (MySQL, PostgreSQL, SQLite), enabling developers to write database applications more easily, quickly, and securely.

Software Architecture

---

• 0. About Acl Project

• 1. Six Core Modules

  • 1.1. Basic Network Module
  • 1.2. Coroutine
  • 1.3. HTTP Module
  • 1.4. Redis Client
  • 1.5. MQTT Module
  • 1.6. Server Framework

• 2. Other Important Modules

  • 2.1. MIME Module
  • 2.2. Codec Module
  • 2.3. Database Module
  • 2.4. Connection Pool Manager
  • 2.5. Other Client Libraries
  • 2.6. DNS Module

• 3. Platform Support and Compilation

  • 3.1. Compiling Acl on Different Platforms
  • 3.2. Notes on Windows Compilation

• 4. Quick Start

  • 4.1. First Acl Example
  • 4.2. Simple TCP Server
  • 4.3. Simple TCP Client
  • 4.4. Coroutine TCP Server
  • 4.5. HTTP Client Example
  • 4.6. Coroutine HTTP Server
  • 4.7. Redis Client Example

• 5. More Information

  • 5.1. Sample Code
  • 5.2. More Simple Examples
  • 5.3. FAQ
  • 5.4. Open Source License
  • 5.5. Related Links
  • 5.6. Acknowledgments

• 6. Appendix

  • 6.1. Software Layered Architecture
  • 6.2. Project Directory Structure

---

1. Six Core Modules

As a fully-featured C/C++ foundation library, Acl provides rich and practical functionality for application development. The six core modules include: Network Communication, Coroutine, HTTP, Redis Client, MQTT, and Server Framework.

1.1. Basic Network Module

Stream Processing Module
This module is the cornerstone of Acl's network communication, providing a unified streaming communication interface that supports both network streams and file streams. Main features include: - Read data line by line, automatically compatible with \r\n on Windows and \n on UNIX - Read data line by line with automatic removal of trailing newline characters (\n or \r\n) - Read data with custom string delimiters - Read data of specified length - Try to read a line or specified length of data - Detect network IO status - Write a line of data - Formatted data writing (similar to fprintf) - File stream positioning operations (similar to fseek) - Batch write data (similar to UNIX writev) - Truncate files (similar to ftruncate) - Get file size and current file stream pointer position (similar to ftell) - Get local and remote addresses of network streams

Network Operation Module
This module provides complete network operation functionality, including: - Network server listening (supports TCP/UDP/UNIX domain sockets) - Network client connection (supports TCP/UNIX domain sockets) - DNS domain name query and result caching (supports both system API calls and direct DNS protocol) - Socket operations and local network interface information retrieval

Non-blocking Network Stream
Comprehensive support for non-blocking network operations, including non-blocking connections, reads (line reads, specified length reads), writes (line writes, specified length writes, batch writes), etc.

Common Network Application Protocol Library
Built-in implementations of common network application protocols such as HTTP, SMTP, ICMP, etc. The HTTP and ICMP modules support both blocking and non-blocking communication modes. The HTTP protocol in the C++ version of lib_acl_cpp provides both server and client modes: - Server Mode: Provides a Java HttpServlet-like interface, supports Cookie, Session, HTTP MIME file upload, etc. - Client Mode: Supports connection pool and cluster management, chunked transfer, automatic character set conversion, automatic decompression, resume download, and other rich features

Common Network Communication Library
Provides client communication libraries for Memcached, Beanstalk, Handler Socket, etc., all supporting connection pool mode.

1.2. Coroutine

Acl's coroutine module is a mature and stable cross-platform coroutine library that has been widely used and validated in many important projects.

Platform Support - Supports mainstream operating systems including Linux, macOS, Windows, iOS, and Android - Supports multiple CPU architectures including x86, ARM, etc. - Supports multiple event engines including select/poll/epoll/kqueue/iocp/win32 GUI messages

Core Features - Complete DNS Protocol Implementation: DNS protocol is natively implemented in coroutines, DNS API can be used directly in coroutines - System API Hook: Automatically hooks system IO APIs on Unix and Windows platforms to enable coroutine support - Read APIs: read/readv/recv/recvfrom/recvmsg - Write APIs: write/writev/send/sendto/sendmsg/sendfile64 - Socket APIs: socket/listen/accept/connect/setsockopt - Event APIs: select/poll/epoll_create/epoll_ctl/epoll_wait - DNS APIs: gethostbyname/gethostbyname_r/getaddrinfo/freeaddrinfo - Shared Stack Mode: Supports shared stack mode to significantly reduce memory usage

Synchronization Primitives - Coroutine Mutex and Semaphore: For synchronization between coroutines - Coroutine Event: Supports synchronous communication between coroutines and threads

For more details, see Using Acl Coroutine Library

1.3. HTTP Module

Complete implementation of HTTP/1.1 protocol, supporting both client and server application development.

Main Features - Java HttpServlet-like Interface (server side): Provides familiar programming interface, reducing learning curve - Connection Pool Mode (client side): Efficiently manages connection resources, improves performance - Chunked Transfer: Supports streaming data transfer - Compression: Built-in Gzip compression/decompression support - SSL/TLS Encryption: Supports secure encrypted transmission - Resume Download: Supports resume download for large files - Cookie Management: Complete cookie setting and retrieval functionality - Session Management (server side): Built-in session management mechanism - WebSocket Support: Supports WebSocket protocol - HTTP MIME Format: Supports MIME multipart data format - Sync/Async Mode: Flexible choice of communication modes

1.4. Redis Client

Acl's Redis client module is powerful, high-performance, and easy to use, making it an ideal choice for production environments.

Features - Rich Command Support: Supports Redis data types and commands including Bitmap/String/Hash/List/Set/Sorted Set/PubSub/HyperLogLog/Geo/Script/Stream/Server/Cluster - STL-style Interface: Provides STL-like C++ interface for each Redis command, conforming to C++ programming conventions - Smart Cluster Management: Client automatically caches and adapts to changes in Redis cluster hash slots without manual intervention - Multiple Communication Modes: Supports standalone, cluster, and pipeline modes with unified interface - Connection Pool Support: Built-in connection pool supporting standalone and cluster modes, improving resource utilization - High Performance: Excellent performance in cluster and pipeline modes - Automatic Retry: Automatically retries on network errors, improving reliability - Coroutine Friendly: Can be used in shared stack coroutine mode

For more details, see Using Acl Redis Client

1.5. MQTT Module

Acl fully implements the MQTT 3.1.1 protocol with a streaming parser design that can flexibly adapt to various IO modes.

Core Features - Complete MQTT 3.1.1 Protocol Support: Implements all standard commands - CONNECT/CONNACK/PUBLISH/PUBACK/PUBREC/PUBREL/PUBCOMP - SUBSCRIBE/SUBACK/UNSUBSCRIBE/UNSUBACK - PINGREQ/PINGRESP/DISCONNECT - Object-Oriented Design: Each MQTT command corresponds to an independent class with clear structure - Streaming Parser: Independent of IO mode, can be combined with any network communication method - Separation of Parsing and Communication: Data parsing is completely decoupled from network communication, providing high flexibility - Dual-End Support: Can be used for both client and server development

For more details, see Using Acl MQTT

1.6. Server Framework

The server framework is the core module in Acl, helping developers quickly build high-performance backend services (such as web services). Through the code generation tool in app/wizard, a complete service code framework can be generated in seconds.

Architecture Design
The Acl server framework consists of two parts: 1. Service Manager (acl_master): Derived from the famous Postfix MTA's master process, extensively extended to become a general-purpose service manager 2. Service Templates: Provides multiple service templates for developers to choose from

Six Service Templates

• Process Service Model
  One connection per process.
• Advantages: Simple programming, safe and stable
• Disadvantages: Limited concurrency

• Use Cases: High security requirements, low concurrency scenarios

• Thread Service Model
  Each process handles all client connections through a thread pool, using IO event triggering mechanism.

• Advantages: Handle many connections with few threads, relatively simple programming
• Features: Threads are bound only when connections have data, released immediately after processing

• Use Cases: High concurrency scenarios, easier to develop than AIO model

• AIO Service Model (Non-blocking)
  Similar to Nginx/Squid/IRCd, single thread handles many connections in non-blocking IO mode.

• Advantages: High processing efficiency, low resource consumption
• Disadvantages: Higher programming complexity

• Use Cases: Ultra-high concurrency, extreme performance requirements

• Coroutine Service Model
  Combines the high concurrency capability of non-blocking model with the simplicity of synchronous programming.

• Advantages: High concurrency + low programming complexity, sequential IO programming style
• Features: Automatically converts blocking operations to non-blocking processes, improving concurrency

• Use Cases: Preferred choice for high concurrency scenarios, balancing performance and development efficiency

• UDP Service Model
  Service model specifically for UDP communication.

• Use Cases: Applications requiring UDP protocol

• Trigger Service Model
  For handling scheduled tasks in background services (similar to system crontab).

• Use Cases: Scheduled tasks, background scheduling

2. Other Important Modules

2.1. MIME Module

MIME (Multipurpose Internet Mail Extensions) is an important data format standard widely used in email and web applications.

Features - Complete implementation of MIME-related RFC standards: RFC2045/RFC2047/RFC822 - Provides streaming MIME data parser independent of IO model - Can be flexibly used in synchronous or asynchronous IO programs - Supports MIME data parsing and construction

2.2. Codec Module

Acl provides rich codecs, all using streaming parsing design, independent of the IO communication layer.

Supported Codec Formats - JSON: Streaming JSON parser and builder, supports serialization/deserialization between JSON data and C structures, greatly improving development efficiency - XML: Streaming XML parser and builder - Base64: Base64 encoding/decoding - URL: URL encoding/decoding - Others: UUCODE, QPCODE, RFC2047, etc.

2.3. Database Module

Acl provides a unified database abstraction interface to simplify database application development.

Core Features - Unified Interface: Provides unified operation interface for MySQL, PostgreSQL, SQLite - SQL Security: Built-in SQL codec automatically escapes special characters, effectively preventing SQL injection attacks - Dynamic Loading: Uses dynamic library loading, no need to worry about dependencies when not using database functionality - Connection Pool Support: Built-in database connection pool management

2.4. Connection Pool Manager

Acl provides a gener