Connection reuse

libcurl keeps a pool of old connections alive. When one transfer has completedit keeps N connections alive in a connection pool (sometimes also calledconnection cache) so that a subsequent transfer that happens to be able toreuse one of the existing connections can use it instead of creating a newone. Reusing a connection instead of creating a new one offers significantbenefits in speed and required resources.

When libcurl is about to make a new connection for the purposes of doing atransfer, it first checks to see if there is an existing connection in thepool that it can reuse instead. The connection re-use check is done before anyDNS or other name resolving mechanism is used, so it is purely hostnamebased. If there is an existing live connection to the right hostname, a lot ofother properties (port number, protocol, etc) are also checked to see that itcan be used.

Easy API pool

When you are using the easy API, or, more specifically,curl_easy_perform(),libcurl keeps the pool associated with the specific easy handle. Then reusingthe same easy handle ensures libcurl can reuse its connection.

Multi API pool

When you are using the multi API, the connection pool is instead keptassociated with the multi handle. This allows you to cleanup and re-createeasy handles freely without risking losing the connection pool, and it allowsthe connection used by one easy handle to get reused by a separate one in alater transfer. Just reuse the multi handle.

Sharing the connection cache

Since libcurl 7.57.0, applications can use theshare interfaceto have otherwise independent transfers share the same connection pool.

When connections are not reused as you want

libcurl will automatically and always try to reuse connections unlessexplicitly told not to. There are however several reasons why a connection isnot used for a subsequent transfer.

• The server signals that the connection will be closed after this transfer.For example by using theConnection: close HTTP response header or aHTTP/2 or HTTP/3 "go away" frame.

• The HTTP/1 response of a transfer is sent in such a way that a connectionclose is the only way to detect the end of the body. Or just an HTTP/1receive error that makes curl deem that it cannot safely reuse theconnection anymore.

• The connection is deemed "dead" when libcurl tries to reuse it. It mighthappen when the server side has closed the connection after the previoustransfer was completed. It can also happen if a stateful firewall/NAT orsomething in the network path drops the connection or if there is HTTP/2 orHTTP/3 traffic (like PING frames) over the connection when unattended.

• The previous transfer is deemed too old to reuse. IfCURLOPT_MAXLIFETIME_CONN is set, libcurl will not reuse a connection thatis older than the set value in seconds.

• The previous transfer is deemed having idled for too long. By defaultlibcurl never attempts to reuse a connection that has been idle for morethan 118 seconds. This time can be changed withCURLOPT_MAXAGE_CONN.

• If the connection pool is full when a transfer ends and a new connection isabout to get stored there, the oldest idle connection in the pool is closedand discarded and therefore cannot be reused anymore. Increase theconnection pool size withCURLMOPT_MAXCONNECTS orCURLOPT_MAXCONNECTS,depending on which API you are using.

• When using the multi interface, if the previous transfer has not ended whenthe next transfer is started, and the previous connection cannot be usedfor multiplexing.

Etc. Usually you can learn about the reason by enablingCURLOPT_VERBOSE andinspecting what libcurl informs the application.