Comment and debug output fixes.

Debug output 'typo' fix.
Don't print an extra "0x" in
  * Pipe broke: handle 0x0x2546d88, url = /
Add debug output.
Print the number of connections in the connection cache when
  adding one, and not only when one is removed.
Fix typos in comments.
pipelining: Fix connection handling under timeouts.

Data corruption (1420):

This fixes a four year old bug in multi_runsingle(); when a request
times out and then setting CURLM_STATE_COMPLETED, followed by a break
causes the code to continue at the end of the function where the
message is sent to the user with multi_addmsg() after which the state
is set to CURLM_STATE_MSGSENT.

An easy handle in that state never gets out of that state anymore:
the state does nothing. Cleaning up the easy handle from the user
application (after seeing the request is CURLMSG_DONE) doesn't
change that fact. As a result, the easy handle gets stuck, owning
a connection set to 'close' that is never closed or cleaned up.

This commit sets the state to CURLM_STATE_DONE and does NOT break
out of the loop. As a result the easy handle is cleaned up as a
handle with an error, as it should. It's connection is closed.

This commit fixes https://sourceforge.net/p/curl/bugs/1420/
by stopping new requests from being added to such connections
(the changes in ConnectionExists, but actually probably sufficient
that now we close and cleanup the connection) causing their replies
to arrive out of sync.

--
Connection flooding (comments from me in 1420):

While pipelining it is possible that a request never reached the DO
state but still timed out because a request in the pipeline before
it took a long time.

The logic of curl is such that first a new connection is created
and only then the handles on it are checked for timeouts, hence
it is possible that a handle times out without ever having sent
a GET request over their (current) connection. In that case we don't
want to close that connection: it is a healthy connection that probably
was JUST created as replacement for the broken pipe at which the
timeout really occurred.

Note that the 'bits.close' bit is set by default upon construction of
a connectdata struct only to be reset (when the user specifically
requests so) AFTER the connection is established. We can therefore
not use that bit to test if a connection timed out (which also sets
that bit) because the close bit is also set BEFORE it even connects
and when there is a delay between the call to connect() and the
connection being established many requests can be readded before
the first establishes a connection.

This commit fixes both problems by using a new bit (timedout) that is
FALSE upon creation and is only set when the connection times out and
then use this bit to decide if connection should be closed (or can be
reused).

As a result of this commit (using my testsuite available at
https://github.com/CarloWood/curl_http_pipeline_tester) only a single
active connection is created and used when a full pipe breaks due to
a timeout.

That is, although this commit fixes the burst of connect()/close()
calls, the problem remains that the server bundle was refreshed,
so curl forgot about this server being able to do pipelining...
This is fixed in a next commit.
pipelining: Keep bundle when closing broken pipe.

If a request on a pipe times out, it breaks that pipe: the
connection needs to be closed. However, when doing http pipelining
we really don't want to delete the bundle and forget that this
server can do pipelining because that results in a separate connection
for every handle in the pipeline that didn't timeout yet, plus one
for every handle that is added until we receive new headers from the
server again, potentially a lot.

The user application could battle this a little bit by holding back
on adding new requests when it sees a timeout, until it saw a reply
again from the server - but that is an extra burden on the user
application that is unnecessary. Besides, that doesn't guarantee that
multiple connections won't formed due to requests already in the
pipe that didn't timeout yet (i.e. because they were added later than
the one that did).

Although theoretically this is still a leak of the bundle (though note
that before this series of commits it was ALREADY leaking), in practice
a new request WILL*) be added and the bundle will be reused without any
trace of a leak.
*) After all, we're talking about a pipelining server here :p.
pipelining: also keep bundle for a 'retry'.

Also don't delete the bundle when a connection closed that is marked for
retry. The retry will pick up the bundle again, so we still know if it
supports pipelining or not; which is much better than having to detect
that all over again.
pipelining: Add CURLMOPT_PIPELINE_POLICY_FUNCTION

Also adds CURLMOPT_PIPELINE_POLICY_DATA, CURL_SUPPORTS_PIPELINING,
CURL_BLACKLISTED, struct curl_pipeline_policy
and curl_pipeline_policy_callback

This allows the user to tweak the maximum number of connections
per host, the maximum number of requests in a pipeline and
to override blacklisting or implement whitelisting on a per
host basis (since bundles are only per host, not host:port - which
imho is a limitation). Finally they can cause libcurl to start
doing pipelining immediately instead after the first reply
is received.

Usage example:

curl_multi_setopt(multi_handle,
                  CURLMOPT_PIPELINE_POLICY_FUNCTION,
                  &pipeline_policy_callback);

void pipeline_policy_callback(
    char const* hostname,
    int port,
    curl_pipeline_policy* policy,
    void* userp)
{
  if(supports_pipelining(host))
    policy->flags |= CURL_SUPPORTS_PIPELINING;
  if(port == 80)
    policy->flags |= CURL_BLACKLISTED;
  if(host == "special.case" && port == 12340) {
    policy->flags &= ~CURL_BLACKLISTED;
    policy->max_pipeline_length = 100;
  }
  if((policy->flags & CURL_SUPPORTS_PIPELINING))
    policy->max_host_connections = 2;
}
Only assign NULL to data->easy_conn directly.

This commits replaces occurances of *connp = NULL with
data->easy_conn = NULL, adding DEBUGASSERT to make sure
that this is allowed.

What this comes down to is that we only want to set easy_conn
to NULL when the connection is owned by the SessionHandle
that contains that easy_conn. Thus:

  data->easy_conn = NULL;

is only allowed while

  data->easy_conn->data == data

This is a preparation for the next commit that will need this.

Note that this commit also removes a duplicated variable
in curl_multi_remove_handle (nl. 'easy') because it was
an alias for 'data' and having two different variables for
the exact same thing did not make the code better understandable.
In particular, now we can read 'data->easy_conn->data == data'
and 'data->easy_conn->data = data' which matches the above ;)

Finally, in Curl_reconnect_request() we pass connp to
Curl_done() instead of &conn (where conn is a local variable).
The reason is that 'connp' fullfills the above assertion that
Curl_done needs while '&conn' doesn't. There is not functional
difference since 'conn' is not used below this call, *connp
is assigned NULL below that call, and initially conn == *connp.
pipelining: keep used sockets in pipeline active.

This fixes bug https://sourceforge.net/p/curl/bugs/1445/

Libcurl historically has a strict one-on-one relationship between (easy)
handles (struct SessionHandle, often called 'data') and connections
(struct connectdata, often called 'conn'). This is apparent from the fact
that data->easy_conn points to the connectdata that 'data' is using
while conn->data points back to its 'owner'.

Since pipelining this picture has changed: many easy handles can be
using a single connection. While this doesn't seem to pose a problem the
single 'easy_conn' pointer, the single 'conn->data' pointer becomes
questionable. The latter has been partially addressed by stating that
only easy handles at the head of a pipe would be 'owners', but that
still would leave two owner: one request that is at the head of the send
pipe and potentially one that is at the head of the recv pipe. Moreover,
this picture simply doesn't hold: a LOT of code depends on some kind of
relationship without which functionality breaks EVEN when the request
being handled is NOT at a pipe head. This is mostly the case for handles
that timed out (which however is also abused to process newly added
handles which might not be at the head) and for example when handles are
being closed (ie, as a result of a pipe break), etc.

After a deep investigation I determined that the following relationship
is sufficient and required: data->easy_conn->data == data. When at the
right places this relationship is ensured then the code works as
intended. For all other means one has to assume that data->easy_conn can
point to any request-- at 'random'-- and is not useful for pipelining to
be used. Instead one should look at conn->send_pipe and conn->recv_pipe,
which hold all information needed ON TOP of the request being handled
(conn->data, which does not necessarily have to be in either pipe at
all).

This commit centers around a functional bug in how singlesocket()
worked: this function is responsible for adding and removing 'active'
sockets from being watched for activity. It had two problems:
1) when data->easy_conn is set to NULL before calling this function, it
has no direct access to the connectiondata, or send_pipe/recv_pipe
thereof, and hence was not able to take the correct information into
account. The result was that socket were removed from being watched for
activity while other request(s) still existed that needed this.
2) The top part of the function intended to only add new sockets: start
watching them for either POLL_IN or POLL_OUT, but inadvertedly could
switch an action from POLL_OUT to POLL_IN while *another* request in the
send_pipe still needed the POLL_OUT.

The way singlesocket() works is by asking for the current action on the
active sockets on the handle being passed and compare that to the action
that this socket needed last time. From that it is deduced which changes
are needed for that socket. If a removal is needed (of either POLL_IN,
POLL_OUT or both) then it double checks with the send_pipe and recv_pipe
to see if that's ok: if not other requests still need that action, and
if not makes the change.

The solution used to fix problem 1) is that when a socket is
disassociated from a connection (setting easy_conn to NULL) then
immediately it is checked if other requests in the pipes require a
socket to be handled; and if that is the case to also disassociate the
handle from the socket (clearing data->socket[]). This algorithm is
implemented in the new functions Curl_disassociate_socket() and
Curl_disassociate_conn(). The latter is to be called when formerly
easy_conn was set to NULL, except when the connection was freed and/or
could be freed while the connection became unusable for all request.

Note that because of all this, a strict policy needed to be followed:
whenever a connectdata is freed, we do not want an easy_conn to still
point to it; otherwise it might still be accessed (ie, by calling
Curl_disassociate_conn()). Therefore I built in into Curl_disconnect()
that easy_conn is set to NULL when freed. That also means that it is no
longer needed to do that elsewhere (ie, immediately after returning from
Curl_disconnect or as function of some return value), ie, after calling
Curl_async_resolved(). easy_conn is now set to NULL automatically
whenever the connection is freed.

This commit fixes another bug by disassociating all handles from
disconnected sockets (in Curl_disconnect()). Before it was possible that
this same socket fd was reused by another request before old request,
still having that fd in their socket[] area, would -say- time out and
get processed - which could lead to that socket being seens as going
from active to non-active and being removed from select() while still
being used by another connnectdata struct and handles.