1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_STREAM_WEIGHT
5Section: 3
6Source: libcurl
7See-also:
8  - CURLMOPT_PIPELINING (3)
9  - CURLOPT_PIPEWAIT (3)
10  - CURLOPT_STREAM_DEPENDS (3)
11  - CURLOPT_STREAM_DEPENDS_E (3)
12Protocol:
13  - HTTP
14Added-in: 7.46.0
15---
16
17# NAME
18
19CURLOPT_STREAM_WEIGHT - numerical stream weight
20
21# SYNOPSIS
22
23~~~c
24#include <curl/curl.h>
25
26CURLcode curl_easy_setopt(CURL *handle, CURLOPT_STREAM_WEIGHT, long weight);
27~~~
28
29# DESCRIPTION
30
31Set the long *weight* to a number between 1 and 256.
32
33When using HTTP/2, this option sets the individual weight for this particular
34stream used by the easy *handle*. Setting and using weights only makes
35sense and is only usable when doing multiple streams over the same
36connections, which thus implies that you use CURLMOPT_PIPELINING(3).
37
38This option can be set during transfer and causes the updated weight info get
39sent to the server the next time an HTTP/2 frame is sent to the server.
40
41See section 5.3 of RFC 7540 for protocol details.
42
43Streams with the same parent should be allocated resources proportionally
44based on their weight. If you have two streams going, stream A with weight 16
45and stream B with weight 32, stream B gets two thirds (32/48) of the available
46bandwidth (assuming the server can send off the data equally for both
47streams).
48
49# DEFAULT
50
5116
52
53# %PROTOCOLS%
54
55# EXAMPLE
56
57~~~c
58int main(void)
59{
60  CURL *curl = curl_easy_init();
61  CURL *curl2 = curl_easy_init(); /* a second handle */
62  if(curl) {
63    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/one");
64    curl_easy_setopt(curl, CURLOPT_STREAM_WEIGHT, 10L);
65
66    /* the second has twice the weight */
67    curl_easy_setopt(curl2, CURLOPT_URL, "https://example.com/two");
68    curl_easy_setopt(curl2, CURLOPT_STREAM_WEIGHT, 20L);
69
70    /* then add both to a multi handle and transfer them */
71  }
72}
73~~~
74
75# %AVAILABILITY%
76
77# RETURN VALUE
78
79Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
80