diff --git a/docs/design-concept/event-handler.md b/docs/design-concept/event-handler.md index 264647cd..615e4d05 100644 --- a/docs/design-concept/event-handler.md +++ b/docs/design-concept/event-handler.md @@ -3,8 +3,8 @@ title: Event handler function --- Each connection has an event handler function associated with it. That function -must be implemented by user. Event handler is the key element of the Mongoose -application, since it defines application's behavior. This is how an event +must be implemented by the user. Event handler is the key element of the Mongoose +application, since it defines the application's behaviour. This is how an event handler function looks like: ```c @@ -18,14 +18,14 @@ static void ev_handler(struct mg_connection *nc, int ev, void *ev_data) { - `struct mg_connection *nc`: Connection that has received an event. - `int ev`: Event number, defined in `mongoose.h`. For example, when data - arrives on inbound connection `ev` would be `MG_EV_RECV`. + arrives on an inbound connection, `ev` would be `MG_EV_RECV`. - `void *ev_data`: This pointer points to the event-specific data, and it has - different meaning for different events. For example, for `MG_EV_RECV` event, + a different meaning for different events. For example, for an `MG_EV_RECV` event, `ev_data` is an `int *` pointer, pointing to the number of bytes received - from the remote peer and saved into the receive IO buffer. Exact meaning of + from the remote peer and saved into the receive IO buffer. The exact meaning of `ev_data` is described for each event. Protocol-specific events usually have `ev_data` pointing to structures that hold protocol-specific information. NOTE: `struct mg_connection` has `void *user_data` which is a placeholder for -an application-specific data. Mongoose does not use that pointer. Event handler +application-specific data. Mongoose does not use that pointer. Event handler can store any kind of information there. diff --git a/docs/design-concept/events.md b/docs/design-concept/events.md index d8d632c1..9cde686a 100644 --- a/docs/design-concept/events.md +++ b/docs/design-concept/events.md @@ -2,36 +2,36 @@ title: Events --- -Mongoose accepts incoming connections, reads and writes data, and calls -specified event handler for each connection when appropriate. Typical event +Mongoose accepts incoming connections, reads and writes data and calls +specified event handlers for each connection when appropriate. A typical event sequence is this: -- For outbound connection: `MG_EV_CONNECT` -> (`MG_EV_RECV`, `MG_EV_SEND`, +- For an outbound connection: `MG_EV_CONNECT` -> (`MG_EV_RECV`, `MG_EV_SEND`, `MG_EV_POLL` ...) -> `MG_EV_CLOSE` -- For inbound connection: `MG_EV_ACCEPT` -> (`MG_EV_RECV`, `MG_EV_SEND`, +- For an inbound connection: `MG_EV_ACCEPT` -> (`MG_EV_RECV`, `MG_EV_SEND`, `MG_EV_POLL` ...) -> `MG_EV_CLOSE` Below is a list of core events triggered by Mongoose (note that each protocol triggers protocol-specific events in addition to the core ones): -- `MG_EV_ACCEPT`: sent when new server connection is accepted by a listening +- `MG_EV_ACCEPT`: sent when a new server connection is accepted by a listening connection. `void *ev_data` is `union socket_address` of the remote peer. - `MG_EV_CONNECT`: sent when a new outbound connection created by `mg_connect()` either failed or succeeded. `void *ev_data` is `int *success`. If `success` - is 0, then connection has been established, otherwise it contains error code. + is 0, then the connection has been established, otherwise it contains an error code. See `mg_connect_opt()` function for code example. - `MG_EV_RECV`: New data is received and appended to the end of `recv_mbuf`. `void *ev_data` is `int *num_received_bytes`. Typically, event handler should check received data in `nc->recv_mbuf`, discard processed data by calling `mbuf_remove()`, set connection flags `nc->flags` if necessary (see `struct - mg_connection`), and write data the remote peer by output functions like + mg_connection`) and write data the remote peer by output functions like `mg_send()`. - **WARNING**: Mongoose uses `realloc()` to expand receive buffer. It is - user's responsibility to discard processed data from the beginning of receive + **WARNING**: Mongoose uses `realloc()` to expand the receive buffer. It is + the user's responsibility to discard processed data from the beginning of the receive buffer, note the `mbuf_remove()` call in the example above. - `MG_EV_SEND`: Mongoose has written data to the remote peer and discarded @@ -39,14 +39,14 @@ triggers protocol-specific events in addition to the core ones): *num_sent_bytes`. **NOTE**: Mongoose output functions only append data to the - `mg_connection::send_mbuf`, they do not do any socket writes. An actual IO - is done by `mg_mgr_poll()`. `MG_EV_SEND` event is just a notification about + `mg_connection::send_mbuf`. They do not do any socket writes. An actual IO + is done by `mg_mgr_poll()`. An `MG_EV_SEND` event is just a notification about an IO has been done. - `MG_EV_POLL`: Sent to all connections on each invocation of `mg_mgr_poll()`. - This event could be used to do any housekeeping, for example check whether - certain timeout has expired and close the connection, or send heartbeet - message, et cetera. + This event could be used to do any housekeeping, for example check whether a + certain timeout has expired and closes the connection or send heartbeat + message, etc. - `MG_EV_TIMER`: Sent to the connection if `mg_set_timer()` was called.