Skip to content

Commit eb0fc46

Browse files
committed
docs(readme): document segmented parallel download API
1 parent 8e68909 commit eb0fc46

1 file changed

Lines changed: 36 additions & 0 deletions

File tree

README.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ Minimal C++23 HTTP/HTTPS client library with SSE (Server-Sent Events) streaming
77
- HTTP/HTTPS client with connection pooling (keep-alive)
88
- SSE (Server-Sent Events) streaming
99
- Proxy support (HTTP CONNECT)
10+
- Segmented parallel downloads via HTTP Range (aria2-style)
1011
- C++23 modules
1112

1213
## Usage
@@ -28,6 +29,41 @@ auto resp = client.send(mcpplibs::tinyhttps::HttpRequest::post(
2829
));
2930
```
3031

32+
## Parallel downloads
33+
34+
`download_to_file_parallel()` probes the server with `Range: bytes=0-0`; when
35+
the server answers 206 the file is split into segments fetched concurrently
36+
into a pre-allocated file. It falls back to a plain sequential download when
37+
the server ignores Range (200) or the file is too small to split.
38+
39+
```cpp
40+
import mcpplibs.tinyhttps;
41+
namespace https = mcpplibs::tinyhttps;
42+
43+
https::HttpClientConfig cfg;
44+
cfg.maxConnectionsPerFile = 8; // concurrent segment workers
45+
cfg.maxSegments = 16; // aria2 -s: split count (0 = tie to connections)
46+
cfg.minSegmentBytes = 4 << 20; // aria2 --min-split-size: 4 MiB
47+
48+
https::HttpClient client(cfg);
49+
auto result = client.download_to_file_parallel(
50+
"https://example.com/big.iso",
51+
"big.iso",
52+
[](std::int64_t total, std::int64_t done) {
53+
// monotonic progress; total is 0 when unknown
54+
},
55+
[] { return false; } // return true to cancel
56+
);
57+
if (result.ok()) { /* result.bytesWritten, result.expectedBytes, ... */ }
58+
```
59+
60+
Behavior notes:
61+
62+
- Segment boundaries never overlap; interrupted segments resume mid-range on
63+
retry (up to 2 retries per segment).
64+
- Progress callbacks are serialized and monotonically increasing.
65+
- The pre-allocated target file is removed if the download fails.
66+
3167
## 使用 mcpp 构建
3268
3369
### 添加依赖

0 commit comments

Comments
 (0)