getinfo: CURLINFO_QUEUE_TIME_T

Returns the time, in microseconds, during which this transfer was held
in a waiting queue before it started "for real". A transfer might be put
in a queue if after getting started, it cannot create a new connection
etc due to set conditions and limits imposed by the application.

Ref: #12293
Closes #12368

docs/libcurl/curl_easy_getinfo.3

@@ -95,6 +95,9 @@ See \fICURLINFO_PRETRANSFER_TIME(3)\fP
 .IP CURLINFO_PRETRANSFER_TIME_T
 Time from start until just before the transfer begins.
 See \fICURLINFO_PRETRANSFER_TIME_T(3)\fP
+.IP CURLINFO_QUEUE_TIME_T
+Time during which this transfer was held in a waiting queue.
+See \fICURLINFO_QUEUE_TIME_T(3\fP
 .IP CURLINFO_STARTTRANSFER_TIME
 Time from start until just when the first byte is received.
 See \fICURLINFO_STARTTRANSFER_TIME(3)\fP
@@ -259,14 +262,18 @@ An overview of the six time values available from \fIcurl_easy_getinfo(3)\fP
 
 curl_easy_perform()
     |
-    |--NAMELOOKUP
-    |--|--CONNECT
-    |--|--|--APPCONNECT
-    |--|--|--|--PRETRANSFER
-    |--|--|--|--|--STARTTRANSFER
-    |--|--|--|--|--|--TOTAL
-    |--|--|--|--|--|--REDIRECT
+    |--QUEUE_TIME
+    |--|--NAMELOOKUP
+    |--|--|--CONNECT
+    |--|--|--|--APPCONNECT
+    |--|--|--|--|--PRETRANSFER
+    |--|--|--|--|--|--STARTTRANSFER
+    |--|--|--|--|--|--|--TOTAL
+    |--|--|--|--|--|--|--REDIRECT
 .fi
+.IP "QUEUE_TIME"
+\fICURLINFO_QUEUE_TIME_T(3\fP. The time during which the transfer was held in
+a waiting queue before it could start for real. (Added in 8.6.0)
 .IP NAMELOOKUP
 \fICURLINFO_NAMELOOKUP_TIME(3)\fP and \fICURLINFO_NAMELOOKUP_TIME_T(3)\fP.
 The time it took from the start until the name resolving was completed.

docs/libcurl/opts/CURLINFO_QUEUE_TIME_T.3

@@ -0,0 +1,74 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" *
+.\" * This software is licensed as described in the file COPYING, which
+.\" * you should have received as part of this distribution. The terms
+.\" * are also available at https://curl.se/docs/copyright.html.
+.\" *
+.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+.\" * copies of the Software, and permit persons to whom the Software is
+.\" * furnished to do so, under the terms of the COPYING file.
+.\" *
+.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+.\" * KIND, either express or implied.
+.\" *
+.\" * SPDX-License-Identifier: curl
+.\" *
+.\" **************************************************************************
+.\"
+.TH CURLINFO_QUEUE_TIME_T 3 "28 Apr 2018" libcurl libcurl
+.SH NAME
+CURLINFO_QUEUE_TIME_T \- time this transfer was queued
+.SH SYNOPSIS
+.nf
+#include <curl/curl.h>
+
+CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_QUEUE_TIME_T,
+                           curl_off_t *timep);
+.fi
+.SH DESCRIPTION
+Pass a pointer to a curl_off_t to receive the time, in microseconds, this
+transfer was held in a waiting queue before it started "for real". A transfer
+might be put in a queue if after getting started, it cannot create a new
+connection etc due to set conditions and limits imposed by the application.
+
+See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page.
+.SH PROTOCOLS
+All
+.SH EXAMPLE
+.nf
+int main(void)
+{
+  CURL *curl = curl_easy_init();
+  if(curl) {
+    CURLcode res;
+    curl_off_t queue;
+    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
+    res = curl_easy_perform(curl);
+    if(CURLE_OK == res) {
+      res = curl_easy_getinfo(curl, CURLINFO_QUEUE_TIME_T, &queue);
+      if(CURLE_OK == res) {
+        printf("Queued: %" CURL_FORMAT_CURL_OFF_T ".%06ld us", queue / 1000000,
+               (long)(queue % 1000000));
+      }
+    }
+    /* always cleanup */
+    curl_easy_cleanup(curl);
+  }
+}
+.fi
+.SH AVAILABILITY
+Added in 8.6.0
+.SH RETURN VALUE
+Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
+.SH "SEE ALSO"
+.BR curl_easy_getinfo (3),
+.BR curl_easy_setopt (3),
+.BR CURLINFO_STARTTRANSFER_TIME_T (3),
+.BR CURLOPT_TIMEOUT (3)

docs/libcurl/opts/Makefile.inc

@@ -65,6 +65,7 @@ man_MANS =                                      \
   CURLINFO_PROXY_ERROR.3                        \
   CURLINFO_PROXY_SSL_VERIFYRESULT.3             \
   CURLINFO_PROXYAUTH_AVAIL.3                    \
+  CURLINFO_QUEUE_TIME_T.3                       \
   CURLINFO_REDIRECT_COUNT.3                     \
   CURLINFO_REDIRECT_TIME.3                      \
   CURLINFO_REDIRECT_TIME_T.3                    \

docs/libcurl/symbols-in-versions

@@ -469,6 +469,7 @@ CURLINFO_PROXY_ERROR            7.73.0
 CURLINFO_PROXY_SSL_VERIFYRESULT 7.52.0
 CURLINFO_PROXYAUTH_AVAIL        7.10.8
 CURLINFO_PTR                    7.54.1
+CURLINFO_QUEUE_TIME_T           8.6.0
 CURLINFO_REDIRECT_COUNT         7.9.7
 CURLINFO_REDIRECT_TIME          7.9.7
 CURLINFO_REDIRECT_TIME_T        7.61.0