1---
2c: Copyright (C) Daniel Stenberg, <daniel.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)
12---
13
14# NAME
15
16CURLOPT_STREAM_WEIGHT - numerical stream weight
17
18# SYNOPSIS
19
20~~~c
21#include <curl/curl.h>
22
23CURLcode curl_easy_setopt(CURL *handle, CURLOPT_STREAM_WEIGHT, long weight);
24~~~
25
26# DESCRIPTION
27
28Set the long *weight* to a number between 1 and 256.
29
30When using HTTP/2, this option sets the individual weight for this particular
31stream used by the easy *handle*. Setting and using weights only makes
32sense and is only usable when doing multiple streams over the same
33connections, which thus implies that you use CURLMOPT_PIPELINING(3).
34
35This option can be set during transfer and causes the updated weight info get
36sent to the server the next time an HTTP/2 frame is sent to the server.
37
38See section 5.3 of RFC 7540 for protocol details.
39
40Streams with the same parent should be allocated resources proportionally
41based on their weight. If you have two streams going, stream A with weight 16
42and stream B with weight 32, stream B gets two thirds (32/48) of the available
43bandwidth (assuming the server can send off the data equally for both
44streams).
45
46# DEFAULT
47
48If nothing is set, the HTTP/2 protocol itself uses its own default which is
4916.
50
51# PROTOCOLS
52
53HTTP/2
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
77Added in 7.46.0
78
79# RETURN VALUE
80
81Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
82