KNOWN_BUGS: A shared connection cache is not thread-safe

Closes #4915
Closes #5802

docs/KNOWN_BUGS

@@ -102,6 +102,7 @@ problems may have been fixed or changed somewhat since this was written!
  11.8 DoH leaks memory after followlocation
  11.9 DoH doesn't inherit all transfer options
  11.10 Blocking socket operations in non-blocking API
+ 11.11 A shared connection cache is not thread-safe
 
  12. LDAP and OpenLDAP
  12.1 OpenLDAP hangs after returning results
@@ -744,6 +745,14 @@ problems may have been fixed or changed somewhat since this was written!
 
  The list of blocking socket operations is in TODO section "More non-blocking".
 
+11.11 A shared connection cache is not thread-safe
+
+ The share interface offers CURL_LOCK_DATA_CONNECT to have multiple easy
+ handle share a connection cache, but due to how connections are used they are
+ still not thread-safe when used shared.
+
+ See https://github.com/curl/curl/issues/4915
+
 12. LDAP and OpenLDAP
 
 12.1 OpenLDAP hangs after returning results

docs/libcurl/curl_share_setopt.3

@@ -74,10 +74,10 @@ by default. Note this symbol was added in 7.10.3 but was not implemented until
 7.23.0.
 .IP CURL_LOCK_DATA_CONNECT
 Put the connection cache in the share object and make all easy handles using
-this share object share the connection cache. Using this, you can for example
-do multi-threaded libcurl use with one handle in each thread, and yet have a
-shared pool of unused connections and this way get way better connection
-re-use than if you use one separate pool in each thread.
+this share object share the connection cache.
+
+Note that due to a known bug, it is not safe to share connections this way
+between multiple concurrent threads.
 
 Connections that are used for HTTP/1.1 Pipelining or HTTP/2 multiplexing only
 get additional transfers added to them if the existing connection is held by