From 6a3d01ee6b17fce485f5a4813da6ead6aa18a543 Mon Sep 17 00:00:00 2001 From: Deomid Ryabkov Date: Fri, 22 Jul 2016 15:37:46 +0300 Subject: [PATCH] Depend on v7.c properly PUBLISHED_FROM=cf49d0d345e4a7607c535f9578b8ed4160f2fccd --- docs/c-api/net.h/mg_add_sock.md | 4 ++-- docs/c-api/net.h/mg_add_sock_opt.md | 4 ++-- docs/c-api/net.h/mg_bind.md | 2 +- docs/c-api/net.h/mg_bind_opt.md | 14 +++++++------- docs/c-api/net.h/mg_broadcast.md | 6 +++--- docs/c-api/net.h/mg_check_ip_acl.md | 12 ++++++------ docs/c-api/net.h/mg_connect.md | 2 +- docs/c-api/net.h/mg_connect_opt.md | 20 ++++++++++---------- docs/c-api/net.h/mg_enable_javascript.md | 8 ++++---- docs/c-api/net.h/mg_enable_multithreading.md | 6 +++--- docs/c-api/net.h/mg_event_handler_t.md | 2 +- docs/c-api/net.h/mg_mgr_free.md | 4 ++-- docs/c-api/net.h/mg_mgr_init.md | 6 +++--- docs/c-api/net.h/mg_mgr_poll.md | 8 ++++---- docs/c-api/net.h/mg_next.md | 6 +++--- docs/c-api/net.h/mg_printf.md | 2 +- docs/c-api/net.h/mg_send.md | 2 +- docs/c-api/net.h/mg_set_ssl.md | 12 ++++++------ docs/c-api/net.h/mg_set_timer.md | 8 ++++---- docs/c-api/net.h/mg_socketpair.md | 4 ++-- 20 files changed, 66 insertions(+), 66 deletions(-) diff --git a/docs/c-api/net.h/mg_add_sock.md b/docs/c-api/net.h/mg_add_sock.md index 511ae841..268dc334 100644 --- a/docs/c-api/net.h/mg_add_sock.md +++ b/docs/c-api/net.h/mg_add_sock.md @@ -6,8 +6,8 @@ signature: | struct mg_connection *mg_add_sock(struct mg_mgr *, sock_t, mg_event_handler_t); --- -Creates a connection, associates it with the given socket and event handler -and adds it to the manager. +Create a connection, associate it with the given socket and event handler, +and add it to the manager. For more options see the `mg_add_sock_opt` variant. diff --git a/docs/c-api/net.h/mg_add_sock_opt.md b/docs/c-api/net.h/mg_add_sock_opt.md index 678a91cb..9a94aee7 100644 --- a/docs/c-api/net.h/mg_add_sock_opt.md +++ b/docs/c-api/net.h/mg_add_sock_opt.md @@ -8,8 +8,8 @@ signature: | struct mg_add_sock_opts); --- -Creates a connection, associates it with the given socket and event handler -and adds to the manager. +Create a connection, associate it with the given socket and event handler, +and add to the manager. See the `mg_add_sock_opts` structure for a description of the options. diff --git a/docs/c-api/net.h/mg_bind.md b/docs/c-api/net.h/mg_bind.md index 800bba95..b6106219 100644 --- a/docs/c-api/net.h/mg_bind.md +++ b/docs/c-api/net.h/mg_bind.md @@ -7,7 +7,7 @@ signature: | mg_event_handler_t); --- -Creates a listening connection. +Create listening connection. See `mg_bind_opt` for full documentation. diff --git a/docs/c-api/net.h/mg_bind_opt.md b/docs/c-api/net.h/mg_bind_opt.md index 93c9a3d2..4fb514bf 100644 --- a/docs/c-api/net.h/mg_bind_opt.md +++ b/docs/c-api/net.h/mg_bind_opt.md @@ -8,19 +8,19 @@ signature: | struct mg_bind_opts opts); --- -Creates a listening connection. +Create listening connection. -The `address` parameter specifies which address to bind to. It's format is the same +`address` parameter tells which address to bind to. It's format is the same as for the `mg_connect()` call, where `HOST` part is optional. `address` -can just be a port number, e.g. `:8000`. To bind to a specific interface, +can be just a port number, e.g. `:8000`. To bind to a specific interface, an IP address can be specified, e.g. `1.2.3.4:8000`. By default, a TCP -connection is created. To create a UDP connection, prepend a `udp://` prefix, -e.g. `udp://:8000`. To summarise, the `address` paramer has following format: +connection is created. To create UDP connection, prepend `udp://` prefix, +e.g. `udp://:8000`. To summarize, `address` paramer has following format: `[PROTO://][IP_ADDRESS]:PORT`, where `PROTO` could be `tcp` or `udp`. See the `mg_bind_opts` structure for a description of the optional parameters. -Returns a new listening connection or `NULL` on error. -NOTE: The connection remains owned by the manager, do not free(). +Return a new listening connection, or `NULL` on error. +NOTE: Connection remains owned by the manager, do not free(). diff --git a/docs/c-api/net.h/mg_broadcast.md b/docs/c-api/net.h/mg_broadcast.md index 4eda7f3c..94fceb8f 100644 --- a/docs/c-api/net.h/mg_broadcast.md +++ b/docs/c-api/net.h/mg_broadcast.md @@ -6,14 +6,14 @@ signature: | void mg_broadcast(struct mg_mgr *, mg_event_handler_t func, void *, size_t); --- -Passes a message of a given length to all connections. +Pass a message of a given length to all connections. Must be called from a thread that does NOT call `mg_mgr_poll()`. Note that `mg_broadcast()` is the only function that can be, and must be, called from a different (non-IO) thread. `func` callback function will be called by the IO thread for each -connection. When called, the event will be `MG_EV_POLL`, and a message will -be passed as the `ev_data` pointer. Maximum message size is capped +connection. When called, event would be `MG_EV_POLL`, and message will +be passed as `ev_data` pointer. Maximum message size is capped by `MG_CTL_MSG_MESSAGE_SIZE` which is set to 8192 bytes. diff --git a/docs/c-api/net.h/mg_check_ip_acl.md b/docs/c-api/net.h/mg_check_ip_acl.md index ce095eda..957a684f 100644 --- a/docs/c-api/net.h/mg_check_ip_acl.md +++ b/docs/c-api/net.h/mg_check_ip_acl.md @@ -6,22 +6,22 @@ signature: | int mg_check_ip_acl(const char *acl, uint32_t remote_ip); --- -Verifies given IP address against the ACL. +Verify given IP address against the ACL. `remote_ip` - an IPv4 address to check, in host byte order `acl` - a comma separated list of IP subnets: `x.x.x.x/x` or `x.x.x.x`. Each subnet is prepended by either a - or a + sign. A plus sign means allow, where a minus sign means deny. If a subnet mask is omitted, such as `-1.2.3.4`, -it means that only that single IP address is denied. +this means to deny only that single IP address. Subnet masks may vary from 0 to 32, inclusive. The default setting -is to allow all access. On each request the full list is traversed, +is to allow all accesses. On each request the full list is traversed, and the last match wins. Example: `-0.0.0.0/0,+192.168/16` - deny all acccesses, only allow 192.168/16 subnet -To learn more about subnet masks, see this -link:https://en.wikipedia.org/wiki/Subnetwork[Wikipedia page on Subnetwork]. +To learn more about subnet masks, see the +link:https://en.wikipedia.org/wiki/Subnetwork[Wikipedia page on Subnetwork] -Returns -1 if ACL is malformed, 0 if address is disallowed, 1 if allowed. +Return -1 if ACL is malformed, 0 if address is disallowed, 1 if allowed. diff --git a/docs/c-api/net.h/mg_connect.md b/docs/c-api/net.h/mg_connect.md index bbacd8f4..388196e3 100644 --- a/docs/c-api/net.h/mg_connect.md +++ b/docs/c-api/net.h/mg_connect.md @@ -7,7 +7,7 @@ signature: | mg_event_handler_t handler); --- -Connects to a remote host. +Connect to a remote host. See `mg_connect_opt()` for full documentation. diff --git a/docs/c-api/net.h/mg_connect_opt.md b/docs/c-api/net.h/mg_connect_opt.md index 6138274f..d169ded1 100644 --- a/docs/c-api/net.h/mg_connect_opt.md +++ b/docs/c-api/net.h/mg_connect_opt.md @@ -8,11 +8,11 @@ signature: | struct mg_connect_opts opts); --- -Connects to a remote host. +Connect to a remote host. -The `address` format is `[PROTO://]HOST:PORT`. `PROTO` could be `tcp` or `udp`. +`address` format is `[PROTO://]HOST:PORT`. `PROTO` could be `tcp` or `udp`. `HOST` could be an IP address, -IPv6 address (if Mongoose is compiled with `-DMG_ENABLE_IPV6`) or a host +IPv6 address (if Mongoose is compiled with `-DMG_ENABLE_IPV6`), or a host name. If `HOST` is a name, Mongoose will resolve it asynchronously. Examples of valid addresses: `google.com:80`, `udp://1.2.3.4:53`, `10.0.0.1:443`, `[::1]:80` @@ -20,18 +20,18 @@ of valid addresses: `google.com:80`, `udp://1.2.3.4:53`, `10.0.0.1:443`, See the `mg_connect_opts` structure for a description of the optional parameters. -Returns a new outbound connection or `NULL` on error. +Returns a new outbound connection, or `NULL` on error. -NOTE: The connection remains owned by the manager, do not free(). +NOTE: Connection remains owned by the manager, do not free(). -NOTE: To enable IPv6 addresses `-DMG_ENABLE_IPV6` should be specified +NOTE: To enable IPv6 addresses, `-DMG_ENABLE_IPV6` should be specified in the compilation flags. -NOTE: The new connection will receive `MG_EV_CONNECT` as its first event -which will report the connect success status. -If the asynchronous resolution fails or the `connect()` syscall fails for whatever +NOTE: New connection will receive `MG_EV_CONNECT` as it's first event +which will report connect success status. +If asynchronous resolution fail, or `connect()` syscall fail for whatever reason (e.g. with `ECONNREFUSED` or `ENETUNREACH`), then `MG_EV_CONNECT` -event will report failure. Code example below: +event report failure. Code example below: ```c static void ev_handler(struct mg_connection *nc, int ev, void *ev_data) { diff --git a/docs/c-api/net.h/mg_enable_javascript.md b/docs/c-api/net.h/mg_enable_javascript.md index 763151e0..cb275386 100644 --- a/docs/c-api/net.h/mg_enable_javascript.md +++ b/docs/c-api/net.h/mg_enable_javascript.md @@ -7,8 +7,8 @@ signature: | const char *init_js_file_name); --- -Enables server-side JavaScript scripting. -Requires a `-DMG_ENABLE_JAVASCRIPT` compilation flag and V7 engine sources. -V7 instance must not be destroyed during manager's lifetime. -Returns a V7 error. +Enable server-side JavaScript scripting. +Requires `-DMG_ENABLE_JAVASCRIPT` compilation flag, and V7 engine sources. +v7 instance must not be destroyed during manager's lifetime. +Return V7 error. diff --git a/docs/c-api/net.h/mg_enable_multithreading.md b/docs/c-api/net.h/mg_enable_multithreading.md index e45fd3a1..3498e4de 100644 --- a/docs/c-api/net.h/mg_enable_multithreading.md +++ b/docs/c-api/net.h/mg_enable_multithreading.md @@ -6,9 +6,9 @@ signature: | void mg_enable_multithreading(struct mg_connection *nc); --- -Enables multi-threaded handling for the given listening connection `nc`. +Enable multi-threaded handling for the given listening connection `nc`. For each accepted connection, Mongoose will create a separate thread -and run an event handler in that thread. Thus, if an event handler is doing -a blocking call or some long computation, it will not slow down +and run event handler in that thread. Thus, if an event hanler is doing +a blocking call or some long computation, that will not slow down other connections. diff --git a/docs/c-api/net.h/mg_event_handler_t.md b/docs/c-api/net.h/mg_event_handler_t.md index f436d667..af94bb0e 100644 --- a/docs/c-api/net.h/mg_event_handler_t.md +++ b/docs/c-api/net.h/mg_event_handler_t.md @@ -7,5 +7,5 @@ signature: | --- Callback function (event handler) prototype. Must be defined by the user. -Mongoose calls the event handler, passing the events defined below. +Mongoose calls the event handler, passing events defined below. diff --git a/docs/c-api/net.h/mg_mgr_free.md b/docs/c-api/net.h/mg_mgr_free.md index d2df34e4..07ca25d3 100644 --- a/docs/c-api/net.h/mg_mgr_free.md +++ b/docs/c-api/net.h/mg_mgr_free.md @@ -6,7 +6,7 @@ signature: | void mg_mgr_free(struct mg_mgr *); --- -De-initialises Mongoose manager. +De-initializes Mongoose manager. -Closes and deallocates all active connections. +Close and deallocate all active connections. diff --git a/docs/c-api/net.h/mg_mgr_init.md b/docs/c-api/net.h/mg_mgr_init.md index b2d13e77..b59506bd 100644 --- a/docs/c-api/net.h/mg_mgr_init.md +++ b/docs/c-api/net.h/mg_mgr_init.md @@ -6,9 +6,9 @@ signature: | void mg_mgr_init(struct mg_mgr *mgr, void *user_data); --- -Initialise Mongoose manager. Side effect: ignores SIGPIPE signal. -`mgr->user_data` field will be initialised with a `user_data` parameter. -That is an arbitrary pointer, where the user code can associate some data +Initialize Mongoose manager. Side effect: ignores SIGPIPE signal. +`mgr->user_data` field will be initialized with `user_data` parameter. +That is an arbitrary pointer, where user code can associate some data with the particular Mongoose manager. For example, a C++ wrapper class could be written, in which case `user_data` can hold a pointer to the class instance. diff --git a/docs/c-api/net.h/mg_mgr_poll.md b/docs/c-api/net.h/mg_mgr_poll.md index b70c31b6..f25c7595 100644 --- a/docs/c-api/net.h/mg_mgr_poll.md +++ b/docs/c-api/net.h/mg_mgr_poll.md @@ -6,10 +6,10 @@ signature: | time_t mg_mgr_poll(struct mg_mgr *, int milli); --- -This function performs the actual IO and must be called in a loop -(an event loop). It returns the current timestamp. +This function performs the actual IO, and must be called in a loop +(an event loop). Returns the current timestamp. `milli` is the maximum number of milliseconds to sleep. -`mg_mgr_poll()` checks all connections for IO readiness. If at least one -of the connections is IO-ready, `mg_mgr_poll()` triggers the respective +`mg_mgr_poll()` checks all connection for IO readiness. If at least one +of the connections is IO-ready, `mg_mgr_poll()` triggers respective event handlers and returns. diff --git a/docs/c-api/net.h/mg_next.md b/docs/c-api/net.h/mg_next.md index fcd5e1d1..fc817262 100644 --- a/docs/c-api/net.h/mg_next.md +++ b/docs/c-api/net.h/mg_next.md @@ -6,10 +6,10 @@ signature: | struct mg_connection *mg_next(struct mg_mgr *, struct mg_connection *); --- -Iterates over all active connections. +Iterate over all active connections. -Returns the next connection from the list -of active connections or `NULL` if there are no more connections. Below +Returns next connection from the list +of active connections, or `NULL` if there is no more connections. Below is the iteration idiom: ```c diff --git a/docs/c-api/net.h/mg_printf.md b/docs/c-api/net.h/mg_printf.md index 2448235f..281fb4fd 100644 --- a/docs/c-api/net.h/mg_printf.md +++ b/docs/c-api/net.h/mg_printf.md @@ -6,7 +6,7 @@ signature: | int mg_printf(struct mg_connection *, const char *fmt, ...); --- -Sends `printf`-style formatted data to the connection. +Send `printf`-style formatted data to the connection. See `mg_send` for more details on send semantics. diff --git a/docs/c-api/net.h/mg_send.md b/docs/c-api/net.h/mg_send.md index c6963a0d..e1aed3e0 100644 --- a/docs/c-api/net.h/mg_send.md +++ b/docs/c-api/net.h/mg_send.md @@ -6,7 +6,7 @@ signature: | void mg_send(struct mg_connection *, const void *buf, int len); --- -Sends data to the connection. +Send data to the connection. Note that sending functions do not actually push data to the socket. They just append data to the output buffer. MG_EV_SEND will be delivered when diff --git a/docs/c-api/net.h/mg_set_ssl.md b/docs/c-api/net.h/mg_set_ssl.md index cc0a8575..d2b3b654 100644 --- a/docs/c-api/net.h/mg_set_ssl.md +++ b/docs/c-api/net.h/mg_set_ssl.md @@ -7,15 +7,15 @@ signature: | const char *ca_cert); --- -Note: This function is deprecated. Please, use SSL options in mg_connect_opt. +Note: This function is deprecated, please use SSL options in mg_connect_opt. -Enables SSL for a given connection. -`cert` is a server certificate file name for a listening connection +Enable SSL for a given connection. +`cert` is a server certificate file name for a listening connection, or a client certificate file name for an outgoing connection. -The certificate files must be in PEM format. The server certificate file +Certificate files must be in PEM format. Server certificate file must contain a certificate, concatenated with a private key, optionally concatenated with DH parameters. -`ca_cert` is a CA certificate or NULL if peer verification is not +`ca_cert` is a CA certificate, or NULL if peer verification is not required. -Return: NULL on success or error message on error. +Return: NULL on success, or error message on error. diff --git a/docs/c-api/net.h/mg_set_timer.md b/docs/c-api/net.h/mg_set_timer.md index 0b089206..e559c26b 100644 --- a/docs/c-api/net.h/mg_set_timer.md +++ b/docs/c-api/net.h/mg_set_timer.md @@ -6,12 +6,12 @@ signature: | double mg_set_timer(struct mg_connection *c, double timestamp); --- -Schedules an MG_EV_TIMER event to be delivered at `timestamp` time. -`timestamp` is UNIX time (the number of seconds since Epoch). It is +Schedule MG_EV_TIMER event to be delivered at `timestamp` time. +`timestamp` is a UNIX time (a number of seconds since Epoch). It is `double` instead of `time_t` to allow for sub-second precision. -Returns the old timer value. +Return the old timer value. -Example: set the connect timeout to 1.5 seconds: +Example: set connect timeout to 1.5 seconds: ``` c = mg_connect(&mgr, "cesanta.com", ev_handler); diff --git a/docs/c-api/net.h/mg_socketpair.md b/docs/c-api/net.h/mg_socketpair.md index bd36cbce..1509c0f3 100644 --- a/docs/c-api/net.h/mg_socketpair.md +++ b/docs/c-api/net.h/mg_socketpair.md @@ -6,7 +6,7 @@ signature: | int mg_socketpair(sock_t[2], int sock_type); --- -Creates a socket pair. +Create a socket pair. `sock_type` can be either `SOCK_STREAM` or `SOCK_DGRAM`. -Returns 0 on failure and 1 on success. +Return 0 on failure, 1 on success.