Artifactspublic-v0

curl

master
ply4 git calls37 ms289 KiB3 cachedprotocol v2
100 lines3.9 KiBRaw

Rate Limiting Transfers

Rate limiting a transfer means that no more than "n bytes per second" shall be sent or received. It can be set individually for both directions via CURLOPT_MAX_RECV_SPEED_LARGE and CURLOPT_MAX_SEND_SPEED_LARGE. These options may be adjusted for an ongoing transfer.

Implementation Base

ratelimit.[ch] implements struct Curl_rlimit and functions to manage such limits. It has the following properties:

  • rate_per_sec: how many "tokens" can be used per second, 0 for infinite.
  • tokens: the currently available tokens to consume
  • burst_per_sec: an upper limit on tokens available
  • ts: the microsecond timestamp of the last tokens update
  • spare_us: elapsed microseconds that have not counted yet for a token update
  • blocked: if the limit is blocked

Tokens can be drained from an rlimit. This reduces tokens, even to negative values. To enforce the limits, tokens should not be drained further when they reach 0, but such things may happen.

An rlimitcan be asked how long to wait until tokens are positive again. This is given in milliseconds. When token are available, this wait time is 0.

Ideally a user of rlimit would consume the available tokens to 0, then get a wait times of 1000ms, after which the set rate of tokens has regenerated. Rinse and repeat.

Should a user drain twice the amount of the rate, tokens are negative and the wait time is 2 seconds. The spare_us account for the time that has passed for the consumption. When a user takes 250ms to consume the rate, the wait time is then 750ms.

When a user drains nothing for two seconds, the available tokens would grow to twice the rate, unless a burst rate is set.

Finally, an rlimit may be set to blocked and later unblocked again. A blocked rlimit has no tokens available. This works also when the rate is unlimited (rate_per_sec set to 0).

Downloads

rlimit is in data->progress.dl.rlimit. setopt.c initializes it whenever the application sets CURLOPT_MAX_RECV_SPEED_LARGE. This may be done in the middle of a transfer.

rlimit tokens are drained in the "protocol" client writer. Checks for capacity depend on the protocol:

  • HTTP and other plain protocols: transfer.c:sendrecv_dl() reads only up to capacity.
  • HTTP/2: capacity is used to adjust a stream's window size. Since all streams start with 64kb, rlimit takes a few seconds to take effect.
  • HTTP/3: ngtcp2 acknowledges stream data according to capacity. It keeps track of bytes not acknowledged yet. This has the same effect as HTTP/2 window sizes.

(The quiche API does not offer control of ACKs and rlimits for download do not work in that backend.)

Uploads

rlimit is in data->progress.ul.rlimit. setopt.c initializes it whenever the application sets CURLOPT_MAX_SEND_SPEED_LARGE. This may be done in the middle of a transfer.

The upload capacity is checked in Curl_client_read() and readers are only asked to read bytes up to the rlimit capacity. This limits upload of data for all protocols in the same way.

Pause/Unpause

Pausing of up-/downloads sets the corresponding rlimit to blocked. Unpausing removes that block.

Suspending transfers

While obeying the rlimit for up-/download leads to the desired transfer rates, the other issue that needs care is CPU consumption.

rlimits are inspected when computing the "pollset" of a transfer. When a transfer wants to send, but not send tokens are available, the POLLOUT is removed from the pollset. Same for receiving.

For a transfer that is, due to rlimit, not able to progress, the pollset is then empty. No socket events are monitored, no CPU activity happens. For paused transfers, this is sufficient.

Draining rlimit happens when a transfer is in PERFORM state and exhausted limits cause the timer TOOFAST to be set. When the fires, the transfer runs again and rlimits are re-evaluated.

1<!--
2Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
4SPDX-License-Identifier: curl
5-->
7# Rate Limiting Transfers
9Rate limiting a transfer means that no more than "n bytes per second"
10shall be sent or received. It can be set individually for both directions
11via `CURLOPT_MAX_RECV_SPEED_LARGE` and `CURLOPT_MAX_SEND_SPEED_LARGE`. These
12options may be adjusted for an ongoing transfer.
14### Implementation Base
16`ratelimit.[ch]` implements `struct Curl_rlimit` and functions to manage
17such limits. It has the following properties:
19* `rate_per_sec`: how many "tokens" can be used per second, 0 for infinite.
20* `tokens`: the currently available tokens to consume
21* `burst_per_sec`: an upper limit on tokens available
22* `ts`: the microsecond timestamp of the last tokens update
23* `spare_us`: elapsed microseconds that have not counted yet for a token update
24* `blocked`: if the limit is blocked
26Tokens can be *drained* from an `rlimit`. This reduces `tokens`, even to
27negative values. To enforce the limits, tokens should not be drained
28further when they reach 0, but such things may happen.
30An `rlimit`can be asked how long to wait until `tokens` are positive again.
31This is given in milliseconds. When token are available, this wait
32time is 0.
34Ideally a user of `rlimit` would consume the available tokens to 0, then
35get a wait times of 1000ms, after which the set rate of tokens has
36regenerated. Rinse and repeat.
38Should a user drain twice the amount of the rate, tokens are negative
39and the wait time is 2 seconds. The `spare_us` account for the
40time that has passed for the consumption. When a user takes 250ms to
41consume the rate, the wait time is then 750ms.
43When a user drains nothing for two seconds, the available tokens would
44grow to twice the rate, unless a burst rate is set.
46Finally, an `rlimit` may be set to `blocked` and later unblocked again.
47A blocked `rlimit` has no tokens available. This works also when the rate
48is unlimited (`rate_per_sec` set to 0).
50### Downloads
52`rlimit` is in `data->progress.dl.rlimit`. `setopt.c` initializes it whenever
53the application sets `CURLOPT_MAX_RECV_SPEED_LARGE`. This may be done
54in the middle of a transfer.
56`rlimit` tokens are drained in the "protocol" client writer. Checks for
57capacity depend on the protocol:
59* HTTP and other plain protocols: `transfer.c:sendrecv_dl()` reads only
60up to capacity.
61* HTTP/2: capacity is used to adjust a stream's window size. Since all
62streams start with `64kb`, `rlimit` takes a few seconds to take effect.
63* HTTP/3: ngtcp2 acknowledges stream data according to capacity. It
64keeps track of bytes not acknowledged yet. This has the same effect as HTTP/2
65window sizes.
67(The quiche API does not offer control of `ACK`s and `rlimits` for download
68do not work in that backend.)
70### Uploads
72`rlimit` is in `data->progress.ul.rlimit`. `setopt.c` initializes it whenever
73the application sets `CURLOPT_MAX_SEND_SPEED_LARGE`. This may be done
74in the middle of a transfer.
76The upload capacity is checked in `Curl_client_read()` and readers are
77only asked to read bytes up to the `rlimit` capacity. This limits upload
78of data for all protocols in the same way.
80### Pause/Unpause
82Pausing of up-/downloads sets the corresponding `rlimit` to blocked. Unpausing
83removes that block.
85### Suspending transfers
87While obeying the `rlimit` for up-/download leads to the desired transfer
88rates, the other issue that needs care is CPU consumption.
90`rlimits` are inspected when computing the "pollset" of a transfer. When
91a transfer wants to send, but not send tokens are available, the `POLLOUT`
92is removed from the pollset. Same for receiving.
94For a transfer that is, due to `rlimit`, not able to progress, the pollset
95is then empty. No socket events are monitored, no CPU activity
96happens. For paused transfers, this is sufficient.
98Draining `rlimit` happens when a transfer is in `PERFORM` state and
99exhausted limits cause the timer `TOOFAST` to be set. When the fires,
100the transfer runs again and `rlimit`s are re-evaluated.
Diagnostics4 git calls · 37 ms
CallStatusSizeTime037 ms
discover200152 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=152
git.server.agent=gitty/1.0
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch object-format
git.server.fetch=shallow filter sideband-all
git.protocol.version=2
git.pkt.frames=8
git.pkt.data=6
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=152
git.pkt.payload.max=34
ls-refs200149 B · hit3 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=149
git.response.cache=HIT
git.response.duration_ms=3
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=149
git.pkt.payload.max=78
git.ls_refs.count=2
git.ls_refs.head=refs/heads/master
fetchblob:none · deepen 10200287 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=293470
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=31c911efe5652725e930f4d2e60c9060e5f6646d
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=10
git.pkt.data=8
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=293470
git.pkt.payload.max=65516
git.sideband.band1.bytes=293354
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=87
git.pack.bytes=293354
git.pack.ofs_delta=0
git.pack.ref_delta=1
git.pack.chain.max=1
git.pack.trailer=6a646bcda6740bab42e321b51998b52ea15146c0
git.pack.full=86
Open pack map
fetch2001.9 KiB · hit31 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=31
git.response.bytes=1900
git.response.cache=HIT
git.response.duration_ms=31
git.fetch.wants=af72211b7874fbf3c4590d11c135caaf4beab6f0
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=1900
git.pkt.payload.max=1879
git.sideband.band1.bytes=1878
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/curl.git
Ref
refs/heads/master
Commit
31c911efe5652725e930f4d2e60c9060e5f6646d
cf-ray
a5e31a91cc0a3e6e
Request
f6741700…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format