mirror of
https://github.com/yhirose/cpp-httplib.git
synced 2026-11-21 20:01:46 +00:00
Compare commits
22
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
907ac7c546 | ||
|
|
dac2f48003 | ||
|
|
e1bc9c0140 | ||
|
|
114e3d0e46 | ||
|
|
7e32283df3 | ||
|
|
76e1a9c4c9 | ||
|
|
0289c0f528 | ||
|
|
b99ccee3db | ||
|
|
d730627815 | ||
|
|
2a6854c935 | ||
|
|
ddaeb5d83d | ||
|
|
f92079e633 | ||
|
|
7b6af186af | ||
|
|
58bd9a1900 | ||
|
|
1b914e1597 | ||
|
|
c51417f458 | ||
|
|
a69d6a0a35 | ||
|
|
726e4583ef | ||
|
|
a6ab971a3f | ||
|
|
9458c27c7c | ||
|
|
e7a004f509 | ||
|
|
3544f47edd |
No files matched your search
+6
-2
@@ -66,7 +66,7 @@ enum ReadResult : int {
|
|||||||
|
|
||||||
Returned by `read()`. Since `Fail` is `0`, the result works naturally in boolean contexts — `while (ws.read(msg))` continues until the connection closes. When you need to distinguish text from binary, check the return value directly.
|
Returned by `read()`. Since `Fail` is `0`, the result works naturally in boolean contexts — `while (ws.read(msg))` continues until the connection closes. When you need to distinguish text from binary, check the return value directly.
|
||||||
|
|
||||||
`Timeout` is only returned for a read timeout you set yourself with `set_read_timeout()`. It means the timeout elapsed on a message boundary: nothing was consumed and the connection is still open, so you can send on it and read again. The compile-time defaults (`CPPHTTPLIB_WEBSOCKET_SERVER_READ_TIMEOUT_SECOND`, 300 seconds on the server; a client waits forever) are a backstop against a peer that has gone quiet, not a request for control: when one of them elapses, `read()` returns `Fail` and closes the connection, so code that never calls `set_read_timeout()` can keep using `while (ws.read(msg))`.
|
`Timeout` is only returned for a read timeout you set yourself with `set_read_timeout()`. It means the timeout elapsed and the connection is still open, so you can send on it and read again. It can land anywhere, inside a message too: what was read of the message is kept, and the next `read()` goes on from there. The compile-time defaults (`CPPHTTPLIB_WEBSOCKET_SERVER_READ_TIMEOUT_SECOND`, 300 seconds on the server; a client waits forever) are a backstop against a peer that has gone quiet, not a request for control: when one of them elapses, `read()` returns `Fail` and closes the connection, so code that never calls `set_read_timeout()` can keep using `while (ws.read(msg))`.
|
||||||
|
|
||||||
**`msg` is left untouched on `Timeout`.** Because `Timeout` is non-zero, `while (ws.read(msg))` keeps looping — with the *previous* message still in `msg`. Once you set a read timeout, test the result instead:
|
**`msg` is left untouched on `Timeout`.** Because `Timeout` is non-zero, `while (ws.read(msg))` keeps looping — with the *previous* message still in `msg`. Once you set a read timeout, test the result instead:
|
||||||
|
|
||||||
@@ -231,7 +231,7 @@ void set_connection_timeout(const std::chrono::duration<Rep, Period> &duration);
|
|||||||
void set_websocket_ping_interval(time_t sec);
|
void set_websocket_ping_interval(time_t sec);
|
||||||
void set_websocket_max_missed_pongs(int count);
|
void set_websocket_max_missed_pongs(int count);
|
||||||
|
|
||||||
// Socket - the same setters Client has
|
// Socket - the same setters Client has (TCP_NODELAY is on by default here)
|
||||||
void set_tcp_nodelay(bool on);
|
void set_tcp_nodelay(bool on);
|
||||||
void set_address_family(int family);
|
void set_address_family(int family);
|
||||||
void set_ipv6_v6only(bool on);
|
void set_ipv6_v6only(bool on);
|
||||||
@@ -252,6 +252,9 @@ void enable_system_ca(bool enabled);
|
|||||||
void set_server_certificate_verifier(tls::VerifyCallback verifier);
|
void set_server_certificate_verifier(tls::VerifyCallback verifier);
|
||||||
void set_session_verifier(
|
void set_session_verifier(
|
||||||
std::function<SSLVerifierResponse(tls::session_t)> verifier);
|
std::function<SSLVerifierResponse(tls::session_t)> verifier);
|
||||||
|
// Windows only, as on SSLClient (see "Platform-specific Certificate Handling"
|
||||||
|
// in README.md)
|
||||||
|
void enable_windows_certificate_verification(bool enabled);
|
||||||
```
|
```
|
||||||
|
|
||||||
## Examples
|
## Examples
|
||||||
@@ -511,6 +514,7 @@ if (ws.connect()) {
|
|||||||
| `CPPHTTPLIB_WEBSOCKET_CLOSE_TIMEOUT_SECOND` | `5` | Timeout for waiting peer's Close response (seconds) |
|
| `CPPHTTPLIB_WEBSOCKET_CLOSE_TIMEOUT_SECOND` | `5` | Timeout for waiting peer's Close response (seconds) |
|
||||||
| `CPPHTTPLIB_WEBSOCKET_PING_INTERVAL_SECOND` | `30` | Automatic Ping interval for heartbeat (seconds) |
|
| `CPPHTTPLIB_WEBSOCKET_PING_INTERVAL_SECOND` | `30` | Automatic Ping interval for heartbeat (seconds) |
|
||||||
| `CPPHTTPLIB_WEBSOCKET_MAX_MISSED_PONGS` | `0` (disabled) | Close the connection after N consecutive unacked pings |
|
| `CPPHTTPLIB_WEBSOCKET_MAX_MISSED_PONGS` | `0` (disabled) | Close the connection after N consecutive unacked pings |
|
||||||
|
| `CPPHTTPLIB_WEBSOCKET_TCP_NODELAY` | `true` | Set TCP_NODELAY on WebSocket connections, so small messages do not wait on Nagle's algorithm |
|
||||||
|
|
||||||
### Runtime Ping Interval
|
### Runtime Ping Interval
|
||||||
|
|
||||||
|
|||||||
@@ -252,7 +252,7 @@ On Windows, the CryptoAPI check can also be turned off at runtime. The TLS backe
|
|||||||
cli.enable_windows_certificate_verification(false);
|
cli.enable_windows_certificate_verification(false);
|
||||||
```
|
```
|
||||||
|
|
||||||
`WebSocketClient` does not use CryptoAPI; the TLS backend always verifies its chain.
|
`WebSocketClient` verifies the same way and has the same `enable_windows_certificate_verification()`.
|
||||||
|
|
||||||
> [!NOTE]
|
> [!NOTE]
|
||||||
> When using SSL, it seems impossible to avoid SIGPIPE in all cases, since on some operating systems, SIGPIPE can only be suppressed on a per-message basis, but there is no way to make the OpenSSL library do so for its internal communications. If your program needs to avoid being terminated on SIGPIPE, the only fully general way might be to set up a signal handler for SIGPIPE to handle or ignore it yourself.
|
> When using SSL, it seems impossible to avoid SIGPIPE in all cases, since on some operating systems, SIGPIPE can only be suppressed on a per-message basis, but there is no way to make the OpenSSL library do so for its internal communications. If your program needs to avoid being terminated on SIGPIPE, the only fully general way might be to set up a signal handler for SIGPIPE to handle or ignore it yourself.
|
||||||
@@ -919,6 +919,23 @@ svr.set_keep_alive_max_count(2); // Default is 100, 0 for no limit
|
|||||||
svr.set_keep_alive_timeout(10); // Default is 5
|
svr.set_keep_alive_timeout(10); // Default is 5
|
||||||
```
|
```
|
||||||
|
|
||||||
|
#### Keep-alive parking
|
||||||
|
|
||||||
|
```cpp
|
||||||
|
svr.set_keep_alive_parking(true); // Call it before listen()
|
||||||
|
```
|
||||||
|
|
||||||
|
By default, a kept-alive connection holds a worker thread while it waits for its next request, so connections beyond the thread count wait for one to be closed. With keep-alive parking, a connection waiting for its next request is handed to an event loop instead, and goes back to a worker when the request arrives. An idle connection then costs a socket and a few kilobytes instead of a thread, and connections that outnumber the threads take turns.
|
||||||
|
|
||||||
|
With it:
|
||||||
|
|
||||||
|
- Consecutive requests on a connection may run on different threads.
|
||||||
|
- When the [max queued requests](#max-queued-requests) limit is reached, only a connection that has not been served yet (or, with `SSLServer`, has not finished its TLS handshake) is closed. An established one waits for room.
|
||||||
|
- Handing the connection over to a worker adds roughly 10-20 µs to each request. It only shows when the client is as near as loopback and the handlers are very light: in our measurements, 2 connections on 2 threads served about a third fewer requests per second over loopback, but only a few percent fewer with a 250 µs round trip.
|
||||||
|
- A handler, a content provider and a WebSocket still hold their thread while they run.
|
||||||
|
- A subclass that overrides the private `process_and_close_socket()` is bypassed.
|
||||||
|
- `SSLServer` runs the TLS handshake on a worker when the client starts it. Until then the connection waits in the event loop and is closed at the keep-alive timeout, not the read timeout, and `ssl_last_error()` is not set for it.
|
||||||
|
|
||||||
### Client address behind a reverse proxy
|
### Client address behind a reverse proxy
|
||||||
|
|
||||||
```cpp
|
```cpp
|
||||||
@@ -962,7 +979,7 @@ Please see [Server example](https://github.com/yhirose/cpp-httplib/blob/master/e
|
|||||||
|
|
||||||
When a new task arrives and the queued tasks outnumber the idle threads, a temporary thread is spawned (up to the maximum). A dynamic thread exits automatically once it has waited for the idle timeout without receiving a task. The idle timeout defaults to 3 seconds, configurable via `CPPHTTPLIB_THREAD_POOL_IDLE_TIMEOUT`.
|
When a new task arrives and the queued tasks outnumber the idle threads, a temporary thread is spawned (up to the maximum). A dynamic thread exits automatically once it has waited for the idle timeout without receiving a task. The idle timeout defaults to 3 seconds, configurable via `CPPHTTPLIB_THREAD_POOL_IDLE_TIMEOUT`.
|
||||||
|
|
||||||
A connection holds its thread while it is served: between requests up to the keep-alive timeout, through a request body sent slowly but within the read timeout, and for the whole life of a WebSocket. Enough of them leave no thread for anyone else, so in front of untrusted clients, put a reverse proxy that limits connections per client, and reject unwanted WebSocket upgrades in the pre-request handler.
|
A connection holds its thread while it is served: between requests up to the keep-alive timeout (unless [keep-alive parking](#keep-alive-parking) is on), through a request body sent slowly but within the read timeout, and for the whole life of a WebSocket. Enough of them leave no thread for anyone else, so in front of untrusted clients, put a reverse proxy that limits connections per client, and reject unwanted WebSocket upgrades in the pre-request handler.
|
||||||
|
|
||||||
If you want to set the thread counts at runtime:
|
If you want to set the thread counts at runtime:
|
||||||
|
|
||||||
|
|||||||
@@ -34,7 +34,7 @@ svr.set_keep_alive_timeout(10s);
|
|||||||
## Tuning ideas
|
## Tuning ideas
|
||||||
|
|
||||||
**Too many idle connections eating resources**
|
**Too many idle connections eating resources**
|
||||||
Shorten the timeout so idle connections drop and release their worker threads.
|
Shorten the timeout so idle connections drop and release their worker threads. If you want to keep them open, turn on keep-alive parking instead (see below).
|
||||||
|
|
||||||
```cpp
|
```cpp
|
||||||
svr.set_keep_alive_timeout(2s);
|
svr.set_keep_alive_timeout(2s);
|
||||||
@@ -52,6 +52,22 @@ Set `set_keep_alive_max_count(1)` and every request gets its own connection. Mos
|
|||||||
|
|
||||||
## Relationship with the thread pool
|
## Relationship with the thread pool
|
||||||
|
|
||||||
A Keep-Alive connection holds a worker thread for its entire lifetime. The pool adds threads under load, up to its maximum thread count (4× the base count by default). If open connections outnumber that maximum, new connections wait in the queue until one closes. For thread counts, see [S21. Configure the thread pool](../s21-thread-pool).
|
By default, a Keep-Alive connection holds a worker thread for its entire lifetime. The pool adds threads under load, up to its maximum thread count (4× the base count by default). If open connections outnumber that maximum, new connections wait in the queue until one closes. For thread counts, see [S21. Configure the thread pool](../s21-thread-pool).
|
||||||
|
|
||||||
|
## Keep idle connections off the threads
|
||||||
|
|
||||||
|
```cpp
|
||||||
|
svr.set_keep_alive_parking(true); // call it before listen()
|
||||||
|
```
|
||||||
|
|
||||||
|
With keep-alive parking, a connection waiting for its next request is handed to an event loop instead of keeping its worker thread, and goes back to a worker when the request arrives. An idle connection then costs a socket and some memory (a few kilobytes, more with TLS) instead of a thread, and connections that outnumber the threads take turns instead of waiting for one to close. `SSLServer` supports it too.
|
||||||
|
|
||||||
|
What changes with it:
|
||||||
|
|
||||||
|
- Consecutive requests on one connection may run on different threads, so don't keep per-connection state in `thread_local` variables.
|
||||||
|
- Handing the connection over to a worker adds roughly 10-20 µs to each request. It only shows with very light handlers and a client as near as loopback.
|
||||||
|
- A handler, a content provider and a WebSocket still hold their thread while they run.
|
||||||
|
|
||||||
|
The full list is in the [README](https://github.com/yhirose/cpp-httplib/blob/master/README.md#keep-alive-parking).
|
||||||
|
|
||||||
> **Note:** For the client side, see [C14. Understand connection reuse and Keep-Alive behavior](../c14-keep-alive). Even when the server closes the connection on timeout, the client reconnects automatically.
|
> **Note:** For the client side, see [C14. Understand connection reuse and Keep-Alive behavior](../c14-keep-alive). Even when the server closes the connection on timeout, the client reconnects automatically.
|
||||||
@@ -42,7 +42,7 @@ ws.set_write_timeout(10s);
|
|||||||
|
|
||||||
## What the read timeout means
|
## What the read timeout means
|
||||||
|
|
||||||
`set_read_timeout()` applies to a single `read()` call. If no message arrives within that time, `read()` returns `ReadResult::Timeout`: **the connection is still open** and nothing was consumed, so you can send on it and read again. That is what separates it from `ReadResult::Fail`, which means the connection is gone.
|
`set_read_timeout()` applies to a single `read()` call. If no whole message arrives within that time, `read()` returns `ReadResult::Timeout`: **the connection is still open**, and what was read of a message is kept for the next `read()`, so you can send on it and read again. That is what separates it from `ReadResult::Fail`, which means the connection is gone.
|
||||||
|
|
||||||
This is what lets one thread own a connection in both directions:
|
This is what lets one thread own a connection in both directions:
|
||||||
|
|
||||||
@@ -67,7 +67,7 @@ Without a read timeout, `read()` blocks until a message arrives, so the thread h
|
|||||||
Two things to know about `Timeout`:
|
Two things to know about `Timeout`:
|
||||||
|
|
||||||
- It leaves `msg` untouched, and it is non-zero. So `while (ws.read(msg))` is not usable once a read timeout is set — the loop would keep running with the *previous* message still in `msg`.
|
- It leaves `msg` untouched, and it is non-zero. So `while (ws.read(msg))` is not usable once a read timeout is set — the loop would keep running with the *previous* message still in `msg`.
|
||||||
- It is only reported on a message boundary. If the timeout elapses partway through a fragmented message, that message cannot be resumed and `read()` returns `Fail`.
|
- It can land anywhere, partway through a message too. What was read of the message is kept, and the next `read()` goes on from there, so a message that arrives slowly or in fragments still comes out whole.
|
||||||
|
|
||||||
For connections where long idle periods are normal — waiting on notifications, for example — either leave the read timeout unset, or treat `Timeout` as the no-op it is and keep looping.
|
For connections where long idle periods are normal — waiting on notifications, for example — either leave the read timeout unset, or treat `Timeout` as the no-op it is and keep looping.
|
||||||
|
|
||||||
|
|||||||
@@ -34,7 +34,7 @@ svr.set_keep_alive_timeout(10s);
|
|||||||
## チューニングの目安
|
## チューニングの目安
|
||||||
|
|
||||||
**アイドル接続が多くてリソースを食う**
|
**アイドル接続が多くてリソースを食う**
|
||||||
タイムアウトを短めに設定すると、遊んでいる接続がすぐに切れてスレッドが解放されます。
|
タイムアウトを短めに設定すると、遊んでいる接続がすぐに切れてスレッドが解放されます。接続は残したままにしたい場合は、代わりにKeep-Aliveのパーキング(後述)を有効にします。
|
||||||
|
|
||||||
```cpp
|
```cpp
|
||||||
svr.set_keep_alive_timeout(2s);
|
svr.set_keep_alive_timeout(2s);
|
||||||
@@ -52,6 +52,22 @@ svr.set_keep_alive_max_count(1000);
|
|||||||
|
|
||||||
## スレッドプールとの関係
|
## スレッドプールとの関係
|
||||||
|
|
||||||
Keep-Aliveでつながりっぱなしの接続は、その間ずっとワーカースレッドを1つ占有します。スレッドプールは負荷に応じて最大スレッド数(デフォルトはベースの4倍)までスレッドを増やしますが、開いている接続数がそれを超えると、新しい接続はどれかが閉じるまでキューで待たされます。スレッド数の調整は[S21. マルチスレッド数を設定する](../s21-thread-pool)を参照してください。
|
デフォルトでは、Keep-Aliveでつながりっぱなしの接続は、その間ずっとワーカースレッドを1つ占有します。スレッドプールは負荷に応じて最大スレッド数(デフォルトはベースの4倍)までスレッドを増やしますが、開いている接続数がそれを超えると、新しい接続はどれかが閉じるまでキューで待たされます。スレッド数の調整は[S21. マルチスレッド数を設定する](../s21-thread-pool)を参照してください。
|
||||||
|
|
||||||
|
## アイドル接続にスレッドを持たせない
|
||||||
|
|
||||||
|
```cpp
|
||||||
|
svr.set_keep_alive_parking(true); // listen()の前に呼ぶ
|
||||||
|
```
|
||||||
|
|
||||||
|
Keep-Aliveのパーキングを有効にすると、次のリクエストを待っている接続はワーカースレッドを手放してイベントループに預けられ、リクエストが届くとまたワーカーに戻ります。アイドル接続のコストはスレッド1つではなく、ソケットと少しのメモリ(数KB、TLSではもう少し多い)になり、スレッド数より多い接続も、どれかが閉じるのを待たずに順番に処理されます。`SSLServer`でも使えます。
|
||||||
|
|
||||||
|
有効にすると変わること:
|
||||||
|
|
||||||
|
- 同じ接続の連続するリクエストが、別々のスレッドで処理されることがあります。接続ごとの状態を`thread_local`変数に持たせないでください。
|
||||||
|
- ワーカーへの接続の受け渡しで、1リクエストあたり10〜20µsほど時間が増えます。目立つのは、ハンドラがとても軽く、クライアントがループバック並みに近いときだけです。
|
||||||
|
- ハンドラ、コンテンツプロバイダ、WebSocketは、実行中は今までどおりスレッドを占有します。
|
||||||
|
|
||||||
|
すべての変更点は[README](https://github.com/yhirose/cpp-httplib/blob/master/README.md#keep-alive-parking)にあります。
|
||||||
|
|
||||||
> **Note:** クライアント側の挙動は[C14. 接続の再利用とKeep-Aliveの挙動を理解する](../c14-keep-alive)を参照してください。サーバーがタイムアウトで接続を切っても、クライアントは自動で再接続します。
|
> **Note:** クライアント側の挙動は[C14. 接続の再利用とKeep-Aliveの挙動を理解する](../c14-keep-alive)を参照してください。サーバーがタイムアウトで接続を切っても、クライアントは自動で再接続します。
|
||||||
@@ -42,7 +42,7 @@ ws.set_write_timeout(10s);
|
|||||||
|
|
||||||
## 読み取りタイムアウトの意味
|
## 読み取りタイムアウトの意味
|
||||||
|
|
||||||
`set_read_timeout()`は「1回の`read()`呼び出し」に対するタイムアウトです。メッセージが届かないまま指定時間が経過すると`read()`は`ReadResult::Timeout`を返します。このとき**接続は開いたまま**で、1バイトも読み進めていないので、そのまま送信して読み直せます。接続が失われたことを意味する`ReadResult::Fail`とはここが違います。
|
`set_read_timeout()`は「1回の`read()`呼び出し」に対するタイムアウトです。メッセージがそろわないまま指定時間が経過すると`read()`は`ReadResult::Timeout`を返します。このとき**接続は開いたまま**で、途中まで読んだ分は次の`read()`に引き継がれるので、そのまま送信して読み直せます。接続が失われたことを意味する`ReadResult::Fail`とはここが違います。
|
||||||
|
|
||||||
1本の接続を1つのスレッドで双方向に扱えるのはこのためです。
|
1本の接続を1つのスレッドで双方向に扱えるのはこのためです。
|
||||||
|
|
||||||
@@ -67,7 +67,7 @@ while (ws.is_open()) {
|
|||||||
`Timeout`について2点あります。
|
`Timeout`について2点あります。
|
||||||
|
|
||||||
- `msg`は書き換えられません。値も0以外なので、読み取りタイムアウトを設定した状態で`while (ws.read(msg))`と書くと、**前回のメッセージ**が`msg`に残ったままループが回り続けます。
|
- `msg`は書き換えられません。値も0以外なので、読み取りタイムアウトを設定した状態で`while (ws.read(msg))`と書くと、**前回のメッセージ**が`msg`に残ったままループが回り続けます。
|
||||||
- 報告されるのはメッセージの境界だけです。分割されたメッセージの途中でタイムアウトした場合、そのメッセージは再開できないので`read()`は`Fail`を返します。
|
- メッセージの途中でも報告されます。それまでに読んだ分は残り、次の`read()`はその続きから読むので、ゆっくり届くメッセージや分割されたメッセージも、そろった形で受け取れます。
|
||||||
|
|
||||||
通知の待受のように長時間メッセージが来ないことが正常な接続では、読み取りタイムアウトを設定しないままにするか、`Timeout`を「まだ何も来ていない」印として扱ってループを続けてください。
|
通知の待受のように長時間メッセージが来ないことが正常な接続では、読み取りタイムアウトを設定しないままにするか、`Timeout`を「まだ何も来ていない」印として扱ってループを続けてください。
|
||||||
|
|
||||||
|
|||||||
+1076
-5
File diff suppressed because it is too large.
Load diff
Reference in new issue
Block a user