Unverified Commit e649432e authored by Daniel Stenberg's avatar Daniel Stenberg
Browse files

CURLOPT_MAXAGE_CONN: set the maximum allowed age for conn reuse 

... and disconnect too old ones instead of trying to reuse.

Default max age is set to 118 seconds.

Ref: #3722
Closes #3782
parent 060f870b

docs/TODO

+0 −11
Original line number Diff line number Diff line
@@ -35,7 +35,6 @@ 
 1.16 Try to URL encode given URL

 1.17 Add support for IRIs

 1.18 try next proxy if one doesn't work

 1.19 Timeout idle connections from the pool

 1.20 SRV and URI DNS records

 1.21 Have the URL API offer IDN decoding

 1.22 CURLINFO_PAUSE_STATE
@@ -373,16 +372,6 @@ 


 https://github.com/curl/curl/issues/896



1.19 Timeout idle connections from the pool



 libcurl currently keeps connections in its connection pool for an indefinite

 period of time, until it either gets reused, gets noticed that it has been

 closed by the server or gets pruned to make room for a new connection.



 To reduce overhead (especially for when we add monitoring of the connections

 in the pool), we should introduce a timeout so that connections that have

 been idle for N seconds get closed.



1.20 SRV and URI DNS records



 Offer support for resolving SRV and URI DNS records for libcurl to know which

docs/libcurl/curl_easy_setopt.3

+2 −0
Original line number Diff line number Diff line
@@ -468,6 +468,8 @@ Maximum number of connections in the connection pool. See \fICURLOPT_MAXCONNECTS 
Use a new connection. \fICURLOPT_FRESH_CONNECT(3)\fP

.IP CURLOPT_FORBID_REUSE

Prevent subsequent connections from re-using this. See \fICURLOPT_FORBID_REUSE(3)\fP

.IP CURLOPT_MAXAGE_CONN

Limit the age of connections for reuse. See \fICURLOPT_MAXAGE_CONN(3)\fP

.IP CURLOPT_CONNECTTIMEOUT

Timeout for the connection phase. See \fICURLOPT_CONNECTTIMEOUT(3)\fP

.IP CURLOPT_CONNECTTIMEOUT_MS

docs/libcurl/opts/CURLOPT_MAXAGE_CONN.3

0 → 100644
+65 −0
Original line number Diff line number Diff line 
.\" **************************************************************************

.\" *                                  _   _ ____  _

.\" *  Project                     ___| | | |  _ \| |

.\" *                             / __| | | | |_) | |

.\" *                            | (__| |_| |  _ <| |___

.\" *                             \___|\___/|_| \_\_____|

.\" *

.\" * Copyright (C) 2019, 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.haxx.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.

.\" *

.\" **************************************************************************

.\"

.TH CURLOPT_MAXAGE_CONN 3 "18 Apr 2019" "libcurl 7.65.0" "curl_easy_setopt options"

.SH NAME

CURLOPT_MAXAGE_CONN \- max idle time allowed for reusing a connection

.SH SYNOPSIS

#include <curl/curl.h>



CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXAGE_CONN, long maxage);

.SH DESCRIPTION

Pass a long as parameter containing \fImaxage\fP - the maximum time in seconds

that you allow an existing connection to have to be considered for reuse for

this request.



The "connection cache" that holds previously used connections. When a new

request is to be done, it will consider any connection that matches for

reuse. The \fICURLOPT_MAXAGE_CONN(3)\fP limit prevents libcurl from trying

very old connections for reuse, since old connections have a high risk of not

working and thus trying them is a performance loss and sometimes service loss

due to the difficulties to figure out the situation. If a connection is found

in the cache that is older than this set \fImaxage\fP, it will instead be

closed.

.SH DEFAULT

Default maxage is 118 seconds.

.SH PROTOCOLS

All

.SH EXAMPLE

.nf

CURL *curl = curl_easy_init();

if(curl) {

  curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");



  /* only allow 30 seconds idle time */

  curl_easy_setopt(curl, CURLOPT_MAXAGE_CONN, 30L);



  curl_easy_perform(curl);

}

.fi

.SH AVAILABILITY

Added in libcurl 7.65.0

.SH RETURN VALUE

Returns CURLE_OK.

.SH "SEE ALSO"

.BR CURLOPT_TIMEOUT "(3), " CURLOPT_FORBID_REUSE "(3), "

.BR CURLOPT_FRESH_CONNECT "(3), "

docs/libcurl/opts/Makefile.inc

+1 −0
Original line number Diff line number Diff line
@@ -189,6 +189,7 @@ man_MANS = \ 
  CURLOPT_MAIL_AUTH.3                           \

  CURLOPT_MAIL_FROM.3                           \

  CURLOPT_MAIL_RCPT.3                           \

  CURLOPT_MAXAGE_CONN.3                         \

  CURLOPT_MAXCONNECTS.3                         \

  CURLOPT_MAXFILESIZE.3                         \

  CURLOPT_MAXFILESIZE_LARGE.3                   \

docs/libcurl/symbols-in-versions

+1 −0
Original line number Diff line number Diff line
@@ -463,6 +463,7 @@ CURLOPT_LOW_SPEED_TIME 7.1 
CURLOPT_MAIL_AUTH               7.25.0

CURLOPT_MAIL_FROM               7.20.0

CURLOPT_MAIL_RCPT               7.20.0

CURLOPT_MAXAGE_CONN             7.65.0

CURLOPT_MAXCONNECTS             7.7

CURLOPT_MAXFILESIZE             7.10.8

CURLOPT_MAXFILESIZE_LARGE       7.11.0