aboutsummaryrefslogtreecommitdiff
path: root/docs/libcurl
diff options
context:
space:
mode:
authorLinus Nielsen Feltzing <linus@haxx.se>2013-02-15 11:50:45 +0100
committerLinus Nielsen Feltzing <linus@haxx.se>2013-03-13 23:55:24 +0100
commit0f147887b0d592d5fa72215282e84103eb165ad7 (patch)
tree4ad5bc8185f3f8df0eed54ee45afd26d692b44a0 /docs/libcurl
parent911b2d3f677eb1538d8469d43df5780e8b7c7abc (diff)
Multiple pipelines and limiting the number of connections.
Introducing a number of options to the multi interface that allows for multiple pipelines to the same host, in order to optimize the balance between the penalty for opening new connections and the potential pipelining latency. Two new options for limiting the number of connections: CURLMOPT_MAX_HOST_CONNECTIONS - Limits the number of running connections to the same host. When adding a handle that exceeds this limit, that handle will be put in a pending state until another handle is finished, so we can reuse the connection. CURLMOPT_MAX_TOTAL_CONNECTIONS - Limits the number of connections in total. When adding a handle that exceeds this limit, that handle will be put in a pending state until another handle is finished. The free connection will then be reused, if possible, or closed if the pending handle can't reuse it. Several new options for pipelining: CURLMOPT_MAX_PIPELINE_LENGTH - Limits the pipeling length. If a pipeline is "full" when a connection is to be reused, a new connection will be opened if the CURLMOPT_MAX_xxx_CONNECTIONS limits allow it. If not, the handle will be put in a pending state until a connection is ready (either free or a pipe got shorter). CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE - A pipelined connection will not be reused if it is currently processing a transfer with a content length that is larger than this. CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE - A pipelined connection will not be reused if it is currently processing a chunk larger than this. CURLMOPT_PIPELINING_SITE_BL - A blacklist of hosts that don't allow pipelining. CURLMOPT_PIPELINING_SERVER_BL - A blacklist of server types that don't allow pipelining. See the curl_multi_setopt() man page for details.
Diffstat (limited to 'docs/libcurl')
-rw-r--r--docs/libcurl/curl_multi_setopt.3106
-rw-r--r--docs/libcurl/libcurl-errors.33
-rw-r--r--docs/libcurl/symbols-in-versions8
3 files changed, 117 insertions, 0 deletions
diff --git a/docs/libcurl/curl_multi_setopt.3 b/docs/libcurl/curl_multi_setopt.3
index 9e456a093..99984cf49 100644
--- a/docs/libcurl/curl_multi_setopt.3
+++ b/docs/libcurl/curl_multi_setopt.3
@@ -95,6 +95,112 @@ This option is for the multi handle's use only, when using the easy interface
you should instead use the \fICURLOPT_MAXCONNECTS\fP option.
(Added in 7.16.3)
+.IP CURLMOPT_MAX_HOST_CONNECTIONS
+Pass a long. The set number will be used as the maximum amount of
+simultaneously open connections to a single host. For each new session to
+a host, libcurl will open a new connection up to the limit set by
+CURLMOPT_MAX_HOST_CONNECTIONS. When the limit is reached, the sessions will
+be pending until there are available connections. If CURLMOPT_PIPELINING is
+1, libcurl will try to pipeline if the host is capable of it.
+
+The default value is 0, which means that there is no limit.
+However, for backwards compatibility, setting it to 0 when CURLMOPT_PIPELINING
+is 1 will not be treated as unlimited. Instead it will open only 1 connection
+and try to pipeline on it.
+
+(Added in 7.30.0)
+.IP CURLMOPT_MAX_PIPELINE_LENGTH
+Pass a long. The set number will be used as the maximum amount of requests
+in a pipelined connection. When this limit is reached, libcurl will use another
+connection to the same host (see CURLMOPT_MAX_HOST_CONNECTIONS), or queue the
+requests until one of the pipelines to the host is ready to accept a request.
+Thus, the total number of requests in-flight is CURLMOPT_MAX_HOST_CONNECTIONS *
+CURLMOPT_MAX_PIPELINE_LENGTH.
+The default value is 5.
+
+(Added in 7.30.0)
+.IP CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE
+Pass a long. If a pipelined connection is currently processing a request
+with a Content-Length larger than CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE, that
+connection will not be considered for additional requests, even if it is
+shorter than CURLMOPT_MAX_PIPELINE_LENGTH.
+The default value is 0, which means that the penalization is inactive.
+
+(Added in 7.30.0)
+.IP CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE
+Pass a long. If a pipelined connection is currently processing a
+chunked (Transfer-encoding: chunked) request with a current chunk length
+larger than CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE, that connection will not be
+considered for additional requests, even if it is shorter than
+CURLMOPT_MAX_PIPELINE_LENGTH.
+The default value is 0, which means that the penalization is inactive.
+
+(Added in 7.30.0)
+.IP CURLMOPT_PIPELINING_SITE_BL
+Pass an array of char *, ending with NULL. This is a list of sites that are
+blacklisted from pipelining, i.e sites that are known to not support HTTP
+pipelining. The array is copied by libcurl.
+
+The default value is NULL, which means that there is no blacklist.
+
+Pass a NULL pointer to clear the blacklist.
+
+Example:
+
+.nf
+ site_blacklist[] =
+ {
+ "www.haxx.se",
+ "www.example.com:1234",
+ NULL
+ };
+
+ curl_multi_setopt(m, CURLMOPT_PIPELINE_SITE_BL, site_blacklist);
+.fi
+
+(Added in 7.30.0)
+.IP CURLMOPT_PIPELINING_SERVER_BL
+Pass an array of char *, ending with NULL. This is a list of server types
+prefixes (in the Server: HTTP header) that are blacklisted from pipelining,
+i.e server types that are known to not support HTTP pipelining. The array is
+copied by libcurl.
+
+Note that the comparison matches if the Server: header begins with the string
+in the blacklist, i.e "Server: Ninja 1.2.3" and "Server: Ninja 1.4.0" can
+both be blacklisted by having "Ninja" in the backlist.
+
+The default value is NULL, which means that there is no blacklist.
+
+Pass a NULL pointer to clear the blacklist.
+
+Example:
+
+.nf
+ server_blacklist[] =
+ {
+ "Microsoft-IIS/6.0",
+ "nginx/0.8.54",
+ NULL
+ };
+
+ curl_multi_setopt(m, CURLMOPT_PIPELINE_SERVER_BL, server_blacklist);
+.fi
+
+(Added in 7.30.0)
+.IP CURLMOPT_MAX_TOTAL_CONNECTIONS
+Pass a long. The set number will be used as the maximum amount of
+simultaneously open connections in total. For each new session, libcurl
+will open a new connection up to the limit set by
+CURLMOPT_MAX_TOTAL_CONNECTIONS. When the limit is reached, the sessions will
+be pending until there are available connections. If CURLMOPT_PIPELINING is
+1, libcurl will try to pipeline if the host is capable of it.
+
+The default value is 0, which means that there is no limit.
+However, for backwards compatibility, setting it to 0 when CURLMOPT_PIPELINING
+is 1 will not be treated as unlimited. Instead it will open only 1 connection
+and try to pipeline on it.
+
+(Added in 7.30.0)
.SH RETURNS
The standard CURLMcode for multi interface error codes. Note that it returns a
CURLM_UNKNOWN_OPTION if you try setting an option that this version of libcurl
diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3
index beee3971f..7b6823735 100644
--- a/docs/libcurl/libcurl-errors.3
+++ b/docs/libcurl/libcurl-errors.3
@@ -240,6 +240,9 @@ Mismatch of RTSP Session Identifiers.
Unable to parse FTP file list (during FTP wildcard downloading).
.IP "CURLE_CHUNK_FAILED (88)"
Chunk callback reported error.
+.IP "CURLE_NO_CONNECTION_AVAILABLE (89)"
+(For internal use only, will never be returned by libcurl) No connection
+available, the session will be queued. (added in 7.30.0)
.IP "CURLE_OBSOLETE*"
These error codes will never be returned. They were used in an old libcurl
version and are currently unused.
diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions
index 37b5e277d..5ed3f8477 100644
--- a/docs/libcurl/symbols-in-versions
+++ b/docs/libcurl/symbols-in-versions
@@ -85,6 +85,7 @@ CURLE_LDAP_SEARCH_FAILED 7.1
CURLE_LIBRARY_NOT_FOUND 7.1 7.17.0
CURLE_LOGIN_DENIED 7.13.1
CURLE_MALFORMAT_USER 7.1 7.17.0
+CURLE_NO_CONNECTION_AVAILABLE 7.30.0
CURLE_NOT_BUILT_IN 7.21.5
CURLE_OK 7.1
CURLE_OPERATION_TIMEDOUT 7.10.2
@@ -267,8 +268,15 @@ CURLKHTYPE_DSS 7.19.6
CURLKHTYPE_RSA 7.19.6
CURLKHTYPE_RSA1 7.19.6
CURLKHTYPE_UNKNOWN 7.19.6
+CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE 7.30.0
+CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE 7.30.0
+CURLMOPT_MAX_HOST_CONNECTIONS 7.30.0
+CURLMOPT_MAX_PIPELINE_LENGTH 7.30.0
+CURLMOPT_MAX_TOTAL_CONNECTIONS 7.30.0
CURLMOPT_MAXCONNECTS 7.16.3
CURLMOPT_PIPELINING 7.16.0
+CURLMOPT_PIPELINING_SERVER_BL 7.30.0
+CURLMOPT_PIPELINING_SITE_BL 7.30.0
CURLMOPT_SOCKETDATA 7.15.4
CURLMOPT_SOCKETFUNCTION 7.15.4
CURLMOPT_TIMERDATA 7.16.0