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):
1 2 3 4 5 6 7 8 9 10 11 12 13 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):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 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):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 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_; int eventfd_; int timeout_; std::atomic<int > load_; std::atomic<bool > shutdown_; std::list<event*> evlist_; std::vector<epoll_event> events_; 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):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 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):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 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 () ; void addloop () ; void adjust_task () ; 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):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 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):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 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):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 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):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 namespace moon {class eventloop ;class event ;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):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 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):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 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):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 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):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 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) ; void enable_tcp_accept () ; void disable_tcp_accept () ; eventloop* getloop () ; eventloop* dispatch () ; 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) ; void handle_close (base_event* ev) ; private : std::mutex events_mutex_; eventloop base_; looptpool pool_; acceptor acceptor_; int port_; bool tcp_enable_; std::list<base_event*> events_; 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):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 #ifndef _WRAP_H_ #define _WRAP_H_ #ifdef _WIN32 void setreuse (SOCKET fd) ;void setnonblock (SOCKET fd) ;void perr_exit (const char * s) ;#else 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):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 #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 () { 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):
1 moon::server tcp_server (8080 ) ;
创建一个 server
对象,监听 TCP 端口 8080
。
设置回调函数 (Set Callback Functions):
1 tcp_server.set_tcpcb (on_read, nullptr , on_event);
设置缓冲事件的读和错误事件的回调函数。
初始化线程池 (Initialize Thread Pool):
初始化线程池,以提高服务器的并发处理能力。
启动服务器 (Start Server):
启动服务器,开始事件循环,监听和处理连接。
UDP 服务器示例 (UDP Server Example) 描述 (Description):
创建一个简单的 UDP 服务器,监听指定端口,接收数据包并回复客户端。
代码示例 (Code Example):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 #include "server.h" #include "udpevent.h" #include <iostream> 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 () { moon::server udp_server (-1 ) ; udp_server.add_udpev (5005 , on_udp_receive, nullptr ); udp_server.start (); return 0 ; }
说明 (Explanation):
创建服务器实例 (Create Server Instance):
1 moon::server udp_server (-1 ) ;
创建一个 server
对象,不启用 TCP 服务。
添加 UDP 事件 (Add UDP Event):
1 udp_server.add_udpev (5005 , on_udp_receive, nullptr );
添加一个 UDP 事件,监听端口 5005
,并设置接收回调函数。
启动服务器 (Start Server):
启动服务器,开始事件循环,监听和处理 UDP 数据包。
定时器示例 (Timer Example) 描述 (Description):
使用定时器定期执行任务,如每隔一秒打印一条消息。
代码示例 (Code Example):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 #include "server.h" #include "timerevent.h" #include <iostream> void on_timer () { std::cout << "Timer triggered!" << std::endl; }int main () { moon::server timer_server (-1 ) ; timer_server.add_timeev (1000 , true , on_timer); timer_server.start (); return 0 ; }
说明 (Explanation):
创建服务器实例 (Create Server Instance):
1 moon::server timer_server (-1 ) ;
创建一个 server
对象,不启用 TCP 服务。
添加定时器事件 (Add Timer Event):
1 timer_server.add_timeev (1000 , true , on_timer);
添加一个定时器事件,设置超时时间为 1000
毫秒(1 秒),true
表示周期性触发。
启动服务器 (Start Server):
启动服务器,开始事件循环,定时器开始工作。
信号处理示例 (Signal Handling Example) 描述 (Description):
使用信号事件处理类,监听并响应特定的 UNIX 信号,如 SIGINT
(Ctrl+C)。
代码示例 (Code Example):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 #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 () { moon::server signal_server (-1 ) ; std::vector<int > signals = {SIGINT, SIGTERM}; signal_server.add_sev (signals, on_signal); signal_server.start (); return 0 ; }
说明 (Explanation):
创建服务器实例 (Create Server Instance):
1 moon::server signal_server (-1 ) ;
创建一个 server
对象,不启用 TCP 服务。
添加信号事件 (Add Signal Event):
1 2 std::vector<int > signals = {SIGINT, SIGTERM}; signal_server.add_sev (signals, on_signal);
添加一个信号事件,监听 SIGINT
和 SIGTERM
信号,设置回调函数。
启动服务器 (Start Server):
启动服务器,开始事件循环,信号处理开始工作。
错误处理 (Error Handling) MoonNet 使用标准的 POSIX 错误处理机制。当发生错误时,库将调用 perr_exit
函数打印错误消息并终止程序。用户可以根据需要自定义错误处理逻辑,例如修改回调函数以处理特定的错误情况。
示例 (Example):
在 wrap.cpp
中的 perr_exit
函数:
1 2 3 4 void perr_exit (const char *s) { perror (s); exit (1 ); }
自定义错误处理 (Custom Error Handling):
如果希望在发生错误时不直接退出程序,可以修改 perr_exit
函数或在回调函数中添加错误处理逻辑。
示例 (Example):
在回调函数中处理错误而不是退出:
1 2 3 4 void on_event () { std::cerr << "An error occurred on the connection." << std::endl; }
常见问题 (FAQs) 1. 如何同时启用 TCP 和 UDP 服务? 回答 (Answer):
创建一个 server
实例,启用 TCP 服务并添加 UDP 事件。
示例 (Example):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 #include "server.h" #include "bfevent.h" #include "udpevent.h" #include <iostream> 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); } }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 () { moon::server network_server (8080 ) ; network_server.set_tcpcb (on_tcp_read, nullptr , nullptr ); network_server.add_udpev (9090 , on_udp_receive, nullptr ); network_server.init_pool (); network_server.start (); return 0 ; }
2. 如何优雅地关闭服务器? 回答 (Answer):
调用 stop()
方法来中断事件循环,并确保所有资源被正确释放。
示例 (Example):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 #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 () { moon::server network_server (8080 ) ; global_server = &network_server; 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):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 #include "server.h" #include "bfevent.h" #include <iostream> #include <mutex> std::mutex data_mutex;int shared_data = 0 ;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 () { 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 网络库。
如有任何问题或建议,欢迎联系作者或提交问题反馈。