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