MoonNet网络库文档

MoonNet 使用手册

---

概述 (Overview)

MoonNet 是一个基于 C++ 的轻量级、高性能、事件驱动的网络库。它旨在简化网络应用程序的开发，支持 TCP 和 UDP 协议，并提供高效的事件循环机制，用于处理异步 I/O 操作。通过模块化设计，MoonNet 提供了灵活的接口，使开发者能够快速构建高性能的网络服务。

---

目录 (Table of Contents)

1. 模块概述 (Module Overview)
2. 类与接口 (Classes and Interfaces)
   • base_event
   • event
   • eventloop
   • loopthread
   • looptpool
   • Threadpool
   • buffer
   • bfevent
   • udpevent
   • timerevent
   • signalevent
   • acceptor
   • server
   • wrap
3. 使用示例 (Usage Examples)
   • TCP 服务器示例 (TCP Server Example)
   • UDP 服务器示例 (UDP Server Example)
   • 定时器示例 (Timer Example)
   • 信号处理示例 (Signal Handling Example)
4. 错误处理 (Error Handling)
5. 常见问题 (FAQs)
6. 结语 (Conclusion)

---

模块概述 (Module Overview)

MoonNet 的核心模块包括：

• 事件循环 (eventloop)：管理事件的注册、删除和分发，核心的 Reactor 模型实现。
• 事件 (event)：表示文件描述符的事件，封装了事件的回调和触发机制。
• 缓冲区 (buffer)：用于处理非阻塞 I/O 的数据缓冲区，实现数据的缓存和处理。
• 缓冲事件 (bfevent)：基于缓冲区的事件处理类，封装了读写缓冲区和回调函数。
• UDP 事件 (udpevent)：处理 UDP 协议的数据包收发。
• 定时器事件 (timerevent)：提供定时器功能，支持一次性和周期性定时器。
• 信号事件 (signalevent)：处理 UNIX 信号，将信号事件集成到事件循环中。
• 连接器 (acceptor)：监听 TCP 端口并接受新连接。
• 服务器 (server)：封装了 TCP 和 UDP 服务器功能，管理连接、事件和线程池。

---

类与接口 (Classes and Interfaces)

base_event

描述 (Description):

base_event 是所有事件类型的基类，定义了事件的基本接口和行为。

接口 (Interface):

namespace moon {class eventloop;class base_event {
public:virtual ~base_event(){}virtual eventloop* getloop() const = 0;virtual void close() = 0;virtual void disable_cb() = 0;
};}

函数说明 (Function Description):

• virtual eventloop* getloop() const = 0;
  获取关联的事件循环对象。

• virtual void close() = 0;
  关闭事件，释放相关资源。

• virtual void disable_cb() = 0;
  禁用事件的回调函数，防止事件被再次触发。

---

event

描述 (Description):

event 类表示一个文件描述符上的事件，封装了事件的类型、回调函数和触发机制。

接口 (Interface):

namespace moon {class eventloop;// 事件类
class event : public base_event {
public:using Callback = std::function<void()>;event(eventloop* base, int fd, uint32_t events);~event();int getfd() const;                // 获取文件描述符uint32_t getevents() const;       // 获取监听的事件类型eventloop* getloop() const override;void setcb(const Callback& rcb, const Callback& wcb, const Callback& ecb); // 设置回调函数void setrcb(const Callback& rcb); // 设置读事件回调void setwcb(const Callback& wcb); // 设置写事件回调void setecb(const Callback& ecb); // 设置错误事件回调void setrevents(const uint32_t revents); // 设置触发的事件类型void enable_events(uint32_t op);  // 启用指定的事件类型void disable_events(uint32_t op); // 禁用指定的事件类型void update_ep();                 // 更新监听事件void handle_cb();                 // 处理事件回调bool readable();                  // 检查是否可读bool writeable();                 // 检查是否可写void enable_read();               // 启用读事件void disable_read();              // 禁用读事件void enable_write();              // 启用写事件void disable_write();             // 禁用写事件void enable_ET();                 // 启用边缘触发模式void disable_ET();                // 禁用边缘触发模式void reset_events();              // 重置事件类型void del_listen();                // 删除监听void enable_listen();             // 启用监听void disable_cb() override;       // 禁用回调函数void close() override;            // 关闭事件private:eventloop* loop_;int fd_;uint32_t events_;   // 监听的事件uint32_t revents_;  // 触发的事件Callback readcb_;   // 读事件回调Callback writecb_;  // 写事件回调Callback eventcb_;  // 错误事件回调
};}

函数说明 (Function Description):

• event(eventloop* base, int fd, uint32_t events);
  构造函数，初始化事件对象。

• ~event();
  析构函数，释放资源。

• int getfd() const;
  获取事件关联的文件描述符。

• uint32_t getevents() const;
  获取事件的监听类型。

• eventloop* getloop() const override;
  获取关联的事件循环对象。

• void setcb(const Callback& rcb, const Callback& wcb, const Callback& ecb);
  设置读、写和错误事件的回调函数。

• void setrcb(const Callback& rcb);
  设置读事件回调。

• void setwcb(const Callback& wcb);
  设置写事件回调。

• void setecb(const Callback& ecb);
  设置错误事件回调。

• void setrevents(const uint32_t revents);
  设置触发的事件类型。

• void enable_events(uint32_t op);
  启用指定的事件类型。

• void disable_events(uint32_t op);
  禁用指定的事件类型。

• void update_ep();
  更新事件在 epoll 中的状态。

• void handle_cb();
  处理事件，调用相应的回调函数。

• bool readable();
  检查事件是否可读。

• bool writeable();
  检查事件是否可写。

• void enable_read();
  启用读事件监听。

• void disable_read();
  禁用读事件监听。

• void enable_write();
  启用写事件监听。

• void disable_write();
  禁用写事件监听。

• void enable_ET();
  启用边缘触发模式。

• void disable_ET();
  禁用边缘触发模式。

• void reset_events();
  重置事件类型。

• void del_listen();
  删除事件监听。

• void enable_listen();
  启用事件监听。

• void disable_cb() override;
  禁用事件的回调函数。

• void close() override;
  关闭事件。

---

eventloop

描述 (Description):

eventloop 类是事件循环的核心，实现了 Reactor 模型，管理所有事件的注册、删除和分发。

接口 (Interface):

namespace moon {class base_event;
class event;
class loopthread;// 事件循环类
class eventloop {
public:using Callback = std::function<void()>;eventloop(loopthread* base = nullptr, int timeout = -1);~eventloop();loopthread* getbaseloop();int getefd() const;int getevfd() const;int getload() const;// 事件控制函数void add_event(event* event);void del_event(event* event);void mod_event(event* event);void loop();          // 开始事件循环void loopbreak();     // 终止事件循环void getallev(std::list<event*>& list);void create_eventfd();     // 创建通知文件描述符void read_eventfd();void write_eventfd();void add_pending_del(base_event* ev); // 添加待删除的事件private:void updateload(int n); // 更新负载private:int epfd_;                         // epoll 文件描述符int eventfd_;                      // 事件通知文件描述符int timeout_;                      // epoll 超时时间std::atomic<int> load_;            // 负载（活跃事件数）std::atomic<bool> shutdown_;       // 是否关闭事件循环std::list<event*> evlist_;         // 事件列表std::vector<epoll_event> events_;  // epoll 事件数组std::vector<base_event*> delque_;  // 待删除事件队列loopthread* baseloop_;             // 所属的线程
};}

函数说明 (Function Description):

• eventloop(loopthread* base = nullptr, int timeout = -1);
  构造函数，初始化事件循环对象。

• ~eventloop();
  析构函数，释放资源。

• loopthread* getbaseloop();
  获取所属的线程对象。

• int getefd() const;
  获取 epoll 文件描述符。

• int getevfd() const;
  获取事件通知文件描述符。

• int getload() const;
  获取当前事件循环的负载（活跃事件数）。

• void add_event(event* event);
  添加事件到 epoll 监听。

• void del_event(event* event);
  从 epoll 中删除事件。

• void mod_event(event* event);
  修改事件的监听类型。

• void loop();
  开始事件循环，处理事件。

• void loopbreak();
  终止事件循环。

• void getallev(std::list<event*>& list);
  获取所有事件列表。

• void create_eventfd();
  创建事件通知文件描述符。

• void read_eventfd();
  读取事件通知文件描述符，处理终止事件循环的信号。

• void write_eventfd();
  写入事件通知文件描述符，通知事件循环终止。

• void add_pending_del(base_event* ev);
  添加待删除的事件到队列。

---

loopthread

描述 (Description):

loopthread 类封装了一个事件循环线程，用于运行 eventloop。

接口 (Interface):

namespace moon {class eventloop;class loopthread {
public:loopthread(int timeout = -1);~loopthread();eventloop* getloop(); // 获取事件循环对象private:void _init_(); // 初始化事件循环private:eventloop* loop_;std::thread t_;std::mutex mx_;std::condition_variable cv_;int timeout_;
};}

函数说明 (Function Description):

• loopthread(int timeout = -1);
  构造函数，初始化线程并创建事件循环。

• ~loopthread();
  析构函数，终止线程并释放资源。

• eventloop* getloop();
  获取事件循环对象。

• void _init_();
  内部函数，初始化事件循环并开始循环。

---

looptpool

描述 (Description):

looptpool 类管理一组事件循环线程（loopthread），实现线程池功能，并提供静态/动态负载均衡。

接口 (Interface):

namespace moon {class eventloop;
class loopthread;class looptpool {
public:looptpool(eventloop* base, bool dispath = false); // 默认不开启动态负载均衡~looptpool();void create_pool(int timeout = -1);                  // 创建线程池void create_pool(int n, int timeout);                // 指定线程数创建线程池void create_pool_noadjust(int n, int timeout);       // 指定线程数创建线程池，不进行调度管理eventloop* ev_dispatch();    // 分发事件到线程池中的事件循环void delloop_dispatch();     // 删除从 reactor 并分发事件void addloop();              // 添加新的事件循环线程void adjust_task();          // 管理线程任务，动态调度从 reactorint getscale();              // 获取平均负载void enable_adjust();        // 启用动态负载均衡void stop();                 // 停止线程池// 禁用复制和赋值操作looptpool(const looptpool&) = delete;looptpool& operator=(const looptpool&) = delete;private:void init_pool(int timeout = -1); // 初始化线程池eventloop* getminload();          // 获取负载最小的事件循环int getmaxidx();                  // 获取负载最大的事件循环的索引private:eventloop* baseloop_;            // 主事件循环std::thread manager_;            // 管理线程std::vector<eventloop*> loadvec_;// 事件循环列表int next_;                       // 轮询索引int t_num_;                      // 线程数int timeout_;                    // 超时时间int max_tnum_;                   // 最大线程数int min_tnum_;                   // 最小线程数bool dispath_;                   // 是否启用动态调度int coolsec_;                    // 冷却时间int timesec_;                    // 调度时间间隔int scale_max_;                  // 最大负载比例int scale_min_;                  // 最小负载比例
};}

函数说明 (Function Description):

• looptpool(eventloop* base, bool dispath = false);
  构造函数，初始化线程池，是否启用动态负载均衡。

• ~looptpool();
  析构函数，释放资源。

• void create_pool(int timeout = -1);
  创建线程池，使用默认线程数。

• void create_pool(int n, int timeout);
  指定线程数创建线程池。

• void create_pool_noadjust(int n, int timeout);
  指定线程数创建线程池，不进行动态调度。

• eventloop* ev_dispatch();
  分发事件到线程池中的事件循环。

• void delloop_dispatch();
  删除负载最大的事件循环并分发其事件。

• void addloop();
  添加新的事件循环线程。

• void adjust_task();
  管理线程任务，动态调整线程池大小。

• int getscale();
  获取平均负载比例。

• void enable_adjust();
  启用动态负载均衡。

• void stop();
  停止线程池，终止所有事件循环。

---

Threadpool

描述 (Description):

Threadpool 类实现了一个通用的线程池，用于执行任意的任务函数。

接口 (Interface):

namespace moon {class Threadpool {
public:Threadpool(int num);~Threadpool();// 添加任务到线程池template<typename _Fn, typename... _Args>void add_task(_Fn&& fn, _Args&&... args);private:void init();          // 初始化线程池void t_shutdown();    // 销毁线程池void t_task();        // 任务线程入口函数void adjust_task();   // 管理线程入口函数private:std::thread adjust_thr;                    // 管理线程std::vector<std::thread> threads;          // 工作线程std::queue<std::function<void()>> tasks;   // 任务队列std::mutex mx;                             // 互斥锁std::condition_variable task_cv;           // 条件变量int min_thr_num;                           // 最小线程数int max_thr_num;                           // 最大线程数std::atomic<int> run_num;                  // 正在执行任务的线程数std::atomic<int> live_num;                 // 存活线程数std::atomic<int> exit_num;                 // 要销毁的线程数bool shutdown;                             // 线程池是否关闭
};}

函数说明 (Function Description):

• Threadpool(int num);
  构造函数，初始化线程池，指定最小线程数。

• ~Threadpool();
  析构函数，销毁线程池。

• void add_task(_Fn&& fn, _Args&&... args);
  添加任务到线程池，任务函数和参数。

• void init();
  初始化线程池，创建工作线程和管理线程。

• void t_shutdown();
  销毁线程池，终止所有线程。

• void t_task();
  工作线程的入口函数，执行任务。

• void adjust_task();
  管理线程的入口函数，动态调整线程数。

---

buffer

描述 (Description):

buffer 类实现了一个可自动扩展的缓冲区，用于处理非阻塞 I/O 数据的缓存和操作。

接口 (Interface):

namespace moon {class buffer {
public:buffer();~buffer();void append(const char* data, size_t len); // 向缓冲区追加数据size_t remove(char* data, size_t len);     // 从缓冲区读取数据std::string remove(size_t len);            // 从缓冲区读取数据并返回字符串void retrieve(size_t len);                 // 仅移动读指针，标记数据已读size_t readbytes() const;                  // 获取可读数据大小size_t writebytes() const;                 // 获取可写空间大小const char* peek() const;                  // 获取当前读指针位置的数据void reset();                              // 重置缓冲区ssize_t readiov(int fd, int& errnum);      // 从文件描述符读取数据到缓冲区private:void able_wirte(size_t len);               // 确保有足够的可写空间private:std::vector<char> buffer_;uint64_t reader_;    // 读指针位置uint64_t writer_;    // 写指针位置
};}

函数说明 (Function Description):

• buffer();
  构造函数，初始化缓冲区。

• ~buffer();
  析构函数，释放资源。

• void append(const char* data, size_t len);
  向缓冲区追加数据。

• size_t remove(char* data, size_t len);
  从缓冲区读取数据到指定内存。

• std::string remove(size_t len);
  从缓冲区读取数据并返回字符串。

• void retrieve(size_t len);
  仅移动读指针，标记数据已读。

• size_t readbytes() const;
  获取可读数据的字节数。

• size_t writebytes() const;
  获取可写空间的字节数。

• const char* peek() const;
  获取当前读指针位置的数据指针。

• void reset();
  重置缓冲区，清空数据。

• ssize_t readiov(int fd, int& errnum);
  从文件描述符读取数据到缓冲区。

---

bfevent

描述 (Description):

bfevent 类是基于缓冲区的事件处理类，封装了读写缓冲区和回调函数，处理 TCP 连接的数据收发。

接口 (Interface):

namespace moon {class eventloop;
class event;class bfevent : public base_event {
public:using RCallback = std::function<void(bfevent*)>;using Callback = std::function<void()>;bfevent(eventloop* base, int fd, uint32_t events);~bfevent();int getfd() const;eventloop* getloop() const override;buffer* getinbuff();buffer* getoutbuff();bool writeable() const;void setcb(const RCallback& rcb, const Callback& wcb, const Callback& ecb); // 设置回调函数void setrcb(const RCallback& rcb);void setwcb(const Callback& wcb);void setecb(const Callback& ecb);RCallback getrcb();Callback getwcb();Callback getecb();void update_ep();                // 更新监听事件void del_listen();               // 取消监听void enable_listen();            // 启用监听void sendout(const char* data, size_t len);   // 发送数据void sendout(const std::string& data);        // 发送数据size_t receive(char* data, size_t len);       // 接收数据到指定内存std::string receive(size_t len);              // 接收指定长度的数据std::string receive();                        // 接收所有可读数据void enable_events(uint32_t op);  // 启用指定事件void disable_events(uint32_t op); // 禁用指定事件void enable_read();               // 启用读事件void disable_read();              // 禁用读事件void enable_write();              // 启用写事件void disable_write();             // 禁用写事件void enable_ET();                 // 启用边缘触发void disable_ET();                // 禁用边缘触发void disable_cb() override;       // 禁用回调函数void close() override;            // 关闭事件private:void close_event();               // 内部函数，关闭事件void handle_read();               // 处理读事件void handle_write();              // 处理写事件void handle_event();              // 处理错误事件private:eventloop* loop_;int fd_;event* ev_;buffer inbuff_;buffer outbuff_;RCallback readcb_;Callback writecb_;Callback eventcb_;bool closed_;
};}

函数说明 (Function Description):

• bfevent(eventloop* base, int fd, uint32_t events);
  构造函数，初始化缓冲事件对象。

• ~bfevent();
  析构函数，关闭事件并释放资源。

• int getfd() const;
  获取文件描述符。

• eventloop* getloop() const override;
  获取关联的事件循环。

• buffer* getinbuff();
  获取输入缓冲区。

• buffer* getoutbuff();
  获取输出缓冲区。

• bool writeable() const;
  检查是否可写。

• void setcb(const RCallback& rcb, const Callback& wcb, const Callback& ecb);
  设置读、写、错误事件的回调函数。

• void update_ep();
  更新监听事件。

• void del_listen();
  取消监听。

• void enable_listen();
  启用监听。

• void sendout(const char* data, size_t len);
  发送数据。

• void sendout(const std::string& data);
  发送数据。

• size_t receive(char* data, size_t len);
  接收数据到指定内存。

• std::string receive(size_t len);
  接收指定长度的数据。

• std::string receive();
  接收所有可读数据。

• void enable_events(uint32_t op);
  启用指定事件。

• void disable_events(uint32_t op);
  禁用指定事件。

• void enable_read();
  启用读事件。

• void disable_read();
  禁用读事件。

• void enable_write();
  启用写事件。

• void disable_write();
  禁用写事件。

• void enable_ET();
  启用边缘触发。

• void disable_ET();
  禁用边缘触发。

• void disable_cb() override;
  禁用回调函数。

• void close() override;
  关闭事件。

---

udpevent

描述 (Description):

udpevent 类处理 UDP 协议的数据收发，支持非阻塞的 UDP 通信。

接口 (Interface):

namespace moon {class eventloop;
class event;// UDP 事件处理类
class udpevent : public base_event {
public:using Callback = std::function<void()>;using RCallback = std::function<void(const sockaddr_in&, udpevent*)>;udpevent(eventloop* base, int port);~udpevent();buffer* getinbuff();eventloop* getloop() const override;void setcb(const RCallback& rcb, const Callback& ecb);void setrcb(const RCallback& rcb);void setecb(const Callback& ecb);void init_sock(int port);void start();       // 开始监听void stop();        // 停止监听void update_ep();   // 更新监听事件size_t receive(char* data, size_t len);  // 接收数据到指定内存std::string receive(size_t len);         // 接收指定长度的数据std::string receive();                   // 接收所有可读数据void send_to(const std::string& data, const sockaddr_in& addr); // 发送数据到指定地址void enable_read();void disable_read();void enable_ET();void disable_ET();void disable_cb() override;RCallback getrcb();Callback getecb();void close() override; // 关闭事件private:void handle_receive(); // 处理接收事件private:eventloop* loop_;int fd_;event* ev_;buffer inbuff_;RCallback receive_cb_;Callback event_cb_;bool started_;
};}

函数说明 (Function Description):

• udpevent(eventloop* base, int port);
  构造函数，初始化 UDP 事件对象。

• ~udpevent();
  析构函数，关闭事件并释放资源。

• buffer* getinbuff();
  获取输入缓冲区。

• eventloop* getloop() const override;
  获取关联的事件循环。

• void setcb(const RCallback& rcb, const Callback& ecb);
  设置接收和错误事件的回调函数。

• void init_sock(int port);
  初始化 UDP 套接字。

• void start();
  开始监听 UDP 数据包。

• void stop();
  停止监听。

• void update_ep();
  更新监听事件。

• size_t receive(char* data, size_t len);
  从缓冲区接收数据。

• std::string receive(size_t len);
  从缓冲区接收指定长度的数据。

• std::string receive();
  从缓冲区接收所有可读数据。

• void send_to(const std::string& data, const sockaddr_in& addr);
  发送数据到指定的地址。

• void enable_read();
  启用读事件。

• void disable_read();
  禁用读事件。

• void enable_ET();
  启用边缘触发。

• void disable_ET();
  禁用边缘触发。

• void disable_cb() override;
  禁用回调函数。

• void close() override;
  关闭事件。

---

timerevent

描述 (Description):

timerevent 类实现了定时器功能，支持一次性和周期性定时器，用于定期执行任务。

接口 (Interface):

namespace moon {class event;
class eventloop;class timerevent : public base_event {
public:using Callback = std::function<void()>;timerevent(eventloop* loop, int timeout_ms, bool periodic);~timerevent();int getfd() const;eventloop* getloop() const override;void setcb(const Callback& cb);void start();void stop();void close() override;void disable_cb() override;Callback getcb();private:void _init_();void handle_timeout();private:eventloop* loop_;event* ev_;int fd_;int timeout_ms_;bool periodic_;Callback cb_;
};}

函数说明 (Function Description):

• timerevent(eventloop* loop, int timeout_ms, bool periodic);
  构造函数，初始化定时器事件。

• ~timerevent();
  析构函数，关闭定时器并释放资源。

• int getfd() const;
  获取定时器文件描述符。

• eventloop* getloop() const override;
  获取关联的事件循环。

• void setcb(const Callback& cb);
  设置定时器回调函数。

• void start();
  启动定时器。

• void stop();
  停止定时器。

• void close() override;
  关闭定时器事件。

• void disable_cb() override;
  禁用回调函数。

---

signalevent

描述 (Description):

signalevent 类处理 UNIX 信号，将信号事件集成到事件循环中，通过管道机制实现。

接口 (Interface):

namespace moon {class eventloop;
class event;class signalevent : public base_event {
public:using Callback = std::function<void(int)>;signalevent(eventloop* base);~signalevent();eventloop* getloop() const override;void add_signal(int signo);void add_signal(const std::vector<int>& signals);void setcb(const Callback& cb);void enable_listen();void del_listen();void disable_cb() override;void close() override;Callback getcb();private:static void handle_signal(int signo);void handle_read();private:eventloop* loop_;int pipe_fd_[2]; // 管道的读写端event* ev_;Callback cb_;static signalevent* sigev_; // 单例实例
};}

函数说明 (Function Description):

• signalevent(eventloop* base);
  构造函数，初始化信号事件对象。

• ~signalevent();
  析构函数，关闭事件并释放资源。

• void add_signal(int signo);
  添加单个信号监听。

• void add_signal(const std::vector<int>& signals);
  添加多个信号监听。

• void setcb(const Callback& cb);
  设置信号处理回调函数。

• void enable_listen();
  启用信号监听。

• void del_listen();
  停止信号监听。

• void disable_cb() override;
  禁用回调函数。

• void close() override;
  关闭信号事件。

---

acceptor

描述 (Description):

acceptor 类负责监听指定端口，接受新的 TCP 连接，并将新连接交给回调函数处理。

接口 (Interface):

namespace moon {class eventloop;
class event;// 连接器类
class acceptor {
public:using Callback = std::function<void(int)>;acceptor(int port, eventloop* base);~acceptor();void listen();               // 开始监听void stop();                 // 停止监听void init_sock(int port);    // 初始化监听套接字void setcb(const Callback& accept_cb); // 设置回调函数void handle_accept();        // 处理新连接private:int lfd_;           // 监听套接字eventloop* loop_;   // 事件循环event* ev_;         // 事件对象Callback cb_;       // 回调函数bool shutdown_;     // 是否已关闭
};}

函数说明 (Function Description):

• acceptor(int port, eventloop* base);
  构造函数，初始化连接器对象。

• ~acceptor();
  析构函数，关闭监听并释放资源。

• void listen();
  开始监听。

• void stop();
  停止监听。

• void init_sock(int port);
  初始化监听套接字。

• void setcb(const Callback& accept_cb);
  设置新连接到来的回调函数。

• void handle_accept();
  处理新连接事件。

---

server

描述 (Description):

server 类封装了 TCP 和 UDP 服务器功能，管理连接、事件和线程池。

接口 (Interface):

namespace moon {class udpevent;
class signalevent;
class timerevent;class server {
public:using SCallback = std::function<void(int)>;using UCallback = std::function<void(const sockaddr_in&, udpevent*)>;using RCallback = std::function<void(bfevent*)>;using Callback = std::function<void()>;server(int port = -1);~server();void start();                         // 启动服务器void stop();                          // 停止服务器void init_pool(int timeout = -1);     // 初始化线程池void init_pool(int tnum, int timeout);// 指定线程数初始化线程池void init_pool_noadjust(int tnum, int timeout); // 指定线程数初始化线程池，不进行动态调度void enable_tcp(int port);            // 启用 TCP 服务void enable_tcp_accept();             // 启用 TCP 连接监听void disable_tcp_accept();            // 禁用 TCP 连接监听eventloop* getloop();                 // 获取主事件循环eventloop* dispatch();                // 分发事件// 设置 TCP 连接的回调函数void set_tcpcb(const RCallback& rcb, const Callback& wcb, const Callback& ecb);// 事件操作void add_ev(event* ev);void del_ev(event* ev);void mod_ev(event* ev);void add_bev(bfevent* bev);void del_bev(bfevent* bev);void mod_bev(bfevent* bev);void add_udpev(udpevent* uev);udpevent* add_udpev(int port, const UCallback& rcb, const Callback& ecb);void del_udpev(udpevent* uev);void mod_udpev(udpevent* uev);void add_sev(signalevent* sev);signalevent* add_sev(int signo, const SCallback& cb);signalevent* add_sev(const std::vector<int>& signals, const SCallback& cb);void del_sev(signalevent* sev);void add_timeev(timerevent* tev);timerevent* add_timeev(int timeout_ms, bool periodic, const Callback& cb);void del_timeev(timerevent* tev);private:void acceptcb_(int fd); // 处理新连接void tcp_eventcb_(bfevent* bev); // 处理 TCP 错误事件void handle_close(base_event* ev); // 处理事件关闭private:std::mutex events_mutex_;eventloop base_;             // 主事件循环looptpool pool_;             // 线程池acceptor acceptor_;          // 连接器int port_;                   // 端口号bool tcp_enable_;            // 是否启用 TCPstd::list<base_event*> events_; // 事件列表// TCP 连接回调函数RCallback readcb_;Callback writecb_;Callback eventcb_;
};}

函数说明 (Function Description):

• server(int port = -1);
  构造函数，初始化服务器对象。

• ~server();
  析构函数，关闭服务器并释放资源。

• void start();
  启动服务器，开始事件循环。

• void stop();
  停止服务器，终止事件循环。

• void init_pool(int timeout = -1);
  初始化线程池。

• void enable_tcp(int port);
  启用 TCP 服务。

• void enable_tcp_accept();
  启用 TCP 连接监听。

• void disable_tcp_accept();
  禁用 TCP 连接监听。

• eventloop* getloop();
  获取主事件循环。

• eventloop* dispatch();
  分发事件到线程池。

• void set_tcpcb(const RCallback& rcb, const Callback& wcb, const Callback& ecb);
  设置 TCP 连接的回调函数。

• void add_ev(event* ev);
  添加事件。

• void del_ev(event* ev);
  删除事件。

• void mod_ev(event* ev);
  修改事件。

• void add_bev(bfevent* bev);
  添加缓冲事件。

• void del_bev(bfevent* bev);
  删除缓冲事件。

• void mod_bev(bfevent* bev);
  修改缓冲事件。

• void add_udpev(udpevent* uev);
  添加 UDP 事件。

• udpevent* add_udpev(int port, const UCallback& rcb, const Callback& ecb);
  添加并初始化 UDP 事件。

• void del_udpev(udpevent* uev);
  删除 UDP 事件。

• void mod_udpev(udpevent* uev);
  修改 UDP 事件。

• void add_sev(signalevent* sev);
  添加信号事件。

• signalevent* add_sev(int signo, const SCallback& cb);
  添加并初始化信号事件。

• void del_sev(signalevent* sev);
  删除信号事件。

• timerevent* add_timeev(int timeout_ms, bool periodic, const Callback& cb);
  添加并初始化定时器事件。

• void del_timeev(timerevent* tev);
  删除定时器事件。

---

wrap

描述 (Description):

wrap 模块封装了跨平台的套接字操作函数，为 Windows 和 Unix 系统提供统一的接口。

接口 (Interface):

#ifndef _WRAP_H_
#define _WRAP_H_#ifdef _WIN32// Windows 平台的套接字封装函数
void setreuse(SOCKET fd);
void setnonblock(SOCKET fd);
void perr_exit(const char* s);
// 其他函数定义...#else// Unix/Linux 平台的套接字封装函数
void settcpnodelay(int fd);
void setreuse(int fd);
void setnonblock(int fd);
void perr_exit(const char* s);
int Accept(int fd, struct sockaddr* sa, socklen_t* salenptr);
int Bind(int fd, const struct sockaddr* sa, socklen_t salen);
int Connect(int fd, const struct sockaddr* sa, socklen_t salen);
int Listen(int fd, int backlog);
int Socket(int family, int type, int protocol);
ssize_t Read(int fd, void* ptr, size_t nbytes);
ssize_t Write(int fd, const void* ptr, size_t nbytes);
int Close(int fd);
ssize_t Readn(int fd, void* vptr, size_t n);
ssize_t Writen(int fd, const void* vptr, size_t n);
ssize_t Readline(int fd, void* vptr, size_t maxlen);
// 其他函数定义...#endif#endif

函数说明 (Function Description):

• void settcpnodelay(int fd);
  设置套接字为无延迟模式（TCP_NODELAY）。

• void setreuse(int fd);
  设置套接字地址和端口可重用。

• void setnonblock(int fd);
  设置套接字为非阻塞模式。

• void perr_exit(const char* s);
  打印错误信息并退出程序。

• int Accept(int fd, struct sockaddr* sa, socklen_t* salenptr);
  接受新的连接。

• int Bind(int fd, const struct sockaddr* sa, socklen_t salen);
  绑定套接字到指定地址和端口。

• int Connect(int fd, const struct sockaddr* sa, socklen_t salen);
  连接到指定的地址和端口。

• int Listen(int fd, int backlog);
  开始监听套接字。

• int Socket(int family, int type, int protocol);
  创建新的套接字。

• ssize_t Read(int fd, void* ptr, size_t nbytes);
  从套接字读取数据。

• ssize_t Write(int fd, const void* ptr, size_t nbytes);
  向套接字写入数据。

• int Close(int fd);
  关闭套接字。

• ssize_t Readn(int fd, void* vptr, size_t n);
  从套接字读取指定字节数的数据。

• ssize_t Writen(int fd, const void* vptr, size_t n);
  向套接字写入指定字节数的数据。

• ssize_t Readline(int fd, void* vptr, size_t maxlen);
  从套接字读取一行数据。

---

使用示例 (Usage Examples)

以下示例展示了如何使用 MoonNet 网络库构建 TCP 和 UDP 服务器，以及如何使用定时器和信号处理功能。

TCP 服务器示例 (TCP Server Example)

描述 (Description):

创建一个简单的 TCP 服务器，监听指定端口，接收客户端连接，并回显接收到的数据。

代码示例 (Code Example):

#include "server.h"
#include "bfevent.h"
#include <iostream>// 读事件回调函数
void on_read(moon::bfevent* bev) {std::string data = bev->receive();if (!data.empty()) {std::cout << "Received: " << data << std::endl;// 回显数据bev->sendout(data);}
}// 写事件回调函数
void on_write(){...
}// 其他事件回调函数（如错误）
void on_event() {std::cout << "An error occurred on the connection." << std::endl;
}int main() {// 创建服务器，监听端口 8080moon::server tcp_server(8080);// 设置缓冲事件的回调函数tcp_server.set_tcpcb(on_read, on_write, on_event);// 初始化线程池（可选）tcp_server.init_pool();// 启动服务器tcp_server.start();return 0;
}

说明 (Explanation):

1. 创建服务器实例 (Create Server Instance):

   moon::server tcp_server(8080);
   

   创建一个 server 对象，监听 TCP 端口 8080。

2. 设置回调函数 (Set Callback Functions):

   tcp_server.set_tcpcb(on_read, nullptr, on_event);
   

   设置缓冲事件的读和错误事件的回调函数。

3. 初始化线程池 (Initialize Thread Pool):

   tcp_server.init_pool();
   

   初始化线程池，以提高服务器的并发处理能力。

4. 启动服务器 (Start Server):

   tcp_server.start();
   

   启动服务器，开始事件循环，监听和处理连接。

---

UDP 服务器示例 (UDP Server Example)

描述 (Description):

创建一个简单的 UDP 服务器，监听指定端口，接收数据包并回复客户端。

代码示例 (Code Example):

#include "server.h"
#include "udpevent.h"
#include <iostream>// UDP 接收回调函数
void on_udp_receive(const sockaddr_in& addr, moon::udpevent* uev) {std::string data = uev->receive();if (!data.empty()) {std::cout << "UDP Received from " << inet_ntoa(addr.sin_addr)<< ":" << ntohs(addr.sin_port) << " - " << data << std::endl;// 发送回复std::string reply = "Echo: " + data;uev->send_to(reply, addr);}
}int main() {// 创建服务器，不指定 TCP 端口moon::server udp_server(-1);// 添加 UDP 事件，监听端口 5005udp_server.add_udpev(5005, on_udp_receive, nullptr);// 启动服务器udp_server.start();return 0;
}

说明 (Explanation):

1. 创建服务器实例 (Create Server Instance):

   moon::server udp_server(-1);
   

   创建一个 server 对象，不启用 TCP 服务。

2. 添加 UDP 事件 (Add UDP Event):

   udp_server.add_udpev(5005, on_udp_receive, nullptr);
   

   添加一个 UDP 事件，监听端口 5005，并设置接收回调函数。

3. 启动服务器 (Start Server):

   udp_server.start();
   

   启动服务器，开始事件循环，监听和处理 UDP 数据包。

---

定时器示例 (Timer Example)

描述 (Description):

使用定时器定期执行任务，如每隔一秒打印一条消息。

代码示例 (Code Example):

#include "server.h"
#include "timerevent.h"
#include <iostream>// 定时器回调函数
void on_timer() {std::cout << "Timer triggered!" << std::endl;
}int main() {// 创建服务器，不指定 TCP 端口moon::server timer_server(-1);// 添加一个周期性定时器，每 1000 毫秒触发一次timer_server.add_timeev(1000, true, on_timer);// 启动服务器timer_server.start();return 0;
}

说明 (Explanation):

1. 创建服务器实例 (Create Server Instance):

   moon::server timer_server(-1);
   

   创建一个 server 对象，不启用 TCP 服务。

2. 添加定时器事件 (Add Timer Event):

   timer_server.add_timeev(1000, true, on_timer);
   

   添加一个定时器事件，设置超时时间为 1000 毫秒（1 秒），true 表示周期性触发。

3. 启动服务器 (Start Server):

   timer_server.start();
   

   启动服务器，开始事件循环，定时器开始工作。

---

信号处理示例 (Signal Handling Example)

描述 (Description):

使用信号事件处理类，监听并响应特定的 UNIX 信号，如 SIGINT（Ctrl+C）。

代码示例 (Code Example):

#include "server.h"
#include "signalevent.h"
#include <iostream>
#include <vector>
#include <csignal>// 信号处理回调函数
void on_signal(int signo) {std::cout << "Received signal: " << signo << std::endl;// 可以在此执行清理操作或优雅退出
}int main() {// 创建服务器，不指定 TCP 端口moon::server signal_server(-1);// 添加信号事件，监听 SIGINT 和 SIGTERMstd::vector<int> signals = {SIGINT, SIGTERM};signal_server.add_sev(signals, on_signal);// 启动服务器signal_server.start();return 0;
}

说明 (Explanation):

1. 创建服务器实例 (Create Server Instance):

   moon::server signal_server(-1);
   

   创建一个 server 对象，不启用 TCP 服务。

2. 添加信号事件 (Add Signal Event):

   std::vector<int> signals = {SIGINT, SIGTERM};
   signal_server.add_sev(signals, on_signal);
   

   添加一个信号事件，监听 SIGINT 和 SIGTERM 信号，设置回调函数。

3. 启动服务器 (Start Server):

   signal_server.start();
   

   启动服务器，开始事件循环，信号处理开始工作。

---

错误处理 (Error Handling)

MoonNet 使用标准的 POSIX 错误处理机制。当发生错误时，库将调用 perr_exit 函数打印错误消息并终止程序。用户可以根据需要自定义错误处理逻辑，例如修改回调函数以处理特定的错误情况。

示例 (Example):

在 wrap.cpp 中的 perr_exit 函数：

void perr_exit(const char *s) {perror(s);exit(1);
}

自定义错误处理 (Custom Error Handling):

如果希望在发生错误时不直接退出程序，可以修改 perr_exit 函数或在回调函数中添加错误处理逻辑。

示例 (Example):

在回调函数中处理错误而不是退出：

void on_event() {std::cerr << "An error occurred on the connection." << std::endl;// 执行清理操作或尝试恢复
}

---

常见问题 (FAQs)

1. 如何同时启用 TCP 和 UDP 服务？

回答 (Answer):

创建一个 server 实例，启用 TCP 服务并添加 UDP 事件。

示例 (Example):

#include "server.h"
#include "bfevent.h"
#include "udpevent.h"
#include <iostream>// TCP 读回调函数
void on_tcp_read(moon::bfevent* bev) {std::string data = bev->receive();if (!data.empty()) {std::cout << "TCP Received: " << data << std::endl;// 回显数据bev->sendout(data);}
}// UDP 接收回调函数
void on_udp_receive(const sockaddr_in& addr, moon::udpevent* uev) {std::string data = uev->receive();if (!data.empty()) {std::cout << "UDP Received from " << inet_ntoa(addr.sin_addr)<< ":" << ntohs(addr.sin_port) << " - " << data << std::endl;// 发送回复std::string reply = "Echo: " + data;uev->send_to(reply, addr);}
}int main() {// 创建服务器，监听 TCP 端口 8080moon::server network_server(8080);// 设置 TCP 读事件的回调函数network_server.set_tcpcb(on_tcp_read, nullptr, nullptr);// 添加 UDP 事件，监听端口 9090network_server.add_udpev(9090, on_udp_receive, nullptr);// 初始化线程池network_server.init_pool();// 启动服务器network_server.start();return 0;
}

---

2. 如何优雅地关闭服务器？

回答 (Answer):

调用 stop() 方法来中断事件循环，并确保所有资源被正确释放。

示例 (Example):

#include "server.h"
#include "signalevent.h"
#include <iostream>
#include <csignal>moon::server* global_server = nullptr;// 信号处理回调
void on_signal(int signo) {std::cout << "Received signal: " << signo << ", stopping server..." << std::endl;if (global_server) {global_server->stop();}
}int main() {// 创建服务器，监听 TCP 端口 8080moon::server network_server(8080);global_server = &network_server;// 设置 TCP 回调函数（省略）// 添加信号处理，监听 SIGINTnetwork_server.add_sev(SIGINT, on_signal);// 初始化线程池network_server.init_pool();// 启动服务器network_server.start();std::cout << "Server stopped gracefully." << std::endl;return 0;
}

---

3. 如何处理多线程中的数据竞争问题？

回答 (Answer):

MoonNet 内部通过线程池和事件循环的设计，尽量避免了数据竞争问题。各个事件循环运行在独立的线程中，用户在回调函数中处理数据时，应确保对共享资源的访问是线程安全的，可以使用互斥锁（std::mutex）等同步机制。

示例 (Example):

#include "server.h"
#include "bfevent.h"
#include <iostream>
#include <mutex>// 共享资源
std::mutex data_mutex;
int shared_data = 0;// TCP 读回调函数
void on_tcp_read(moon::bfevent* bev) {std::string data = bev->receive();if (!data.empty()) {std::lock_guard<std::mutex> lock(data_mutex);shared_data += data.size();std::cout << "Shared Data Size: " << shared_data << std::endl;}
}int main() {// 创建服务器，监听 TCP 端口 8080moon::server network_server(8080);// 设置缓冲事件的回调函数network_server.set_tcpcb(on_tcp_read, nullptr, nullptr);// 初始化线程池network_server.init_pool();// 启动服务器network_server.start();return 0;
}

---

结语 (Conclusion)

MoonNet 提供了一个高效且易用的网络编程框架，适用于构建各种类型的网络应用程序。通过其模块化设计和灵活的接口，开发者可以快速实现高性能的网络服务。希望本文档能够帮助您更好地理解和使用 MoonNet 网络库。

如有任何问题或建议，欢迎联系作者或提交问题反馈。

---