MoonNet 使用手册
概述 (Overview)
MoonNet 是一个基于 C++ 的轻量级、高性能、事件驱动的网络库。它旨在简化网络应用程序的开发,支持 TCP 和 UDP 协议,并提供高效的事件循环机制,用于处理异步 I/O 操作。通过模块化设计,MoonNet 提供了灵活的接口,使开发者能够快速构建高性能的网络服务。
目录 (Table of Contents)
- 模块概述 (Module Overview)
- 类与接口 (Classes and Interfaces)
- 使用示例 (Usage Examples)
- 错误处理 (Error Handling)
- 常见问题 (FAQs)
- 结语 (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(); // 管理线程任务,动态调度从 reactor
int 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_; // 是否启用 TCP
std::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() {
// 创建服务器,监听端口 8080
moon::server tcp_server(8080);
// 设置缓冲事件的回调函数
tcp_server.set_tcpcb(on_read, on_write, on_event);
// 初始化线程池(可选)
tcp_server.init_pool();
// 启动服务器
tcp_server.start();
return 0;
}
说明 (Explanation):
-
创建服务器实例 (Create Server Instance):
moon::server tcp_server(8080);
创建一个
server
对象,监听 TCP 端口8080
。 -
设置回调函数 (Set Callback Functions):
tcp_server.set_tcpcb(on_read, nullptr, on_event);
设置缓冲事件的读和错误事件的回调函数。
-
初始化线程池 (Initialize Thread Pool):
tcp_server.init_pool();
初始化线程池,以提高服务器的并发处理能力。
-
启动服务器 (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 事件,监听端口 5005
udp_server.add_udpev(5005, on_udp_receive, nullptr);
// 启动服务器
udp_server.start();
return 0;
}
说明 (Explanation):
-
创建服务器实例 (Create Server Instance):
moon::server udp_server(-1);
创建一个
server
对象,不启用 TCP 服务。 -
添加 UDP 事件 (Add UDP Event):
udp_server.add_udpev(5005, on_udp_receive, nullptr);
添加一个 UDP 事件,监听端口
5005
,并设置接收回调函数。 -
启动服务器 (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):
-
创建服务器实例 (Create Server Instance):
moon::server timer_server(-1);
创建一个
server
对象,不启用 TCP 服务。 -
添加定时器事件 (Add Timer Event):
timer_server.add_timeev(1000, true, on_timer);
添加一个定时器事件,设置超时时间为
1000
毫秒(1 秒),true
表示周期性触发。 -
启动服务器 (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 和 SIGTERM
std::vector<int> signals = {SIGINT, SIGTERM};
signal_server.add_sev(signals, on_signal);
// 启动服务器
signal_server.start();
return 0;
}
说明 (Explanation):
-
创建服务器实例 (Create Server Instance):
moon::server signal_server(-1);
创建一个
server
对象,不启用 TCP 服务。 -
添加信号事件 (Add Signal Event):
std::vector<int> signals = {SIGINT, SIGTERM}; signal_server.add_sev(signals, on_signal);
添加一个信号事件,监听
SIGINT
和SIGTERM
信号,设置回调函数。 -
启动服务器 (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 端口 8080
moon::server network_server(8080);
// 设置 TCP 读事件的回调函数
network_server.set_tcpcb(on_tcp_read, nullptr, nullptr);
// 添加 UDP 事件,监听端口 9090
network_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 端口 8080
moon::server network_server(8080);
global_server = &network_server;
// 设置 TCP 回调函数(省略)
// 添加信号处理,监听 SIGINT
network_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 端口 8080
moon::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 网络库。
如有任何问题或建议,欢迎联系作者或提交问题反馈。