Contributing Advent 15: Xdebug connection timeout

For a while people have been complaining that when the remote debugger is enabled, but there is no listening IDE, Xdebug hangs and prevents PHP from loading the script. Bug report #963 is one of those reports, but there is also a report for the Xdebug helper for Chrome.

When Xdebug starts up, and debugging is enabled and requested, it tries to make a connection to the IDE that is supposed to accept the connection and then issue debugging commands. This works all fine if the IDE is actually listening, but if not, then depending on configuration two things can happen:

1. The TCP/IP stack immediately returns with a "can not connect".

2. The TCP/IP stack ignores the connection attempt, and doesn't signal this back.

There is no problem for case 1, as Xdebug will not block and for the duration of the request will not retry to make a debugging connection. But for case 2, Xdebug needs to wait for the Operating System to signal that the connection attempt failed. This time-out limit is about 3 minutes on Linux, and 72 seconds on Windows. You can configure this default on either OS though.

To remedy case 2, we need a way to make the connection attempt to not block in the application (Xdebug). The MongoDB PHP driver for PHP has a similar issue and solves this by putting the socket into non-blocking mode.

I did some investigation and found that Xdebug very naïvely uses a simple call to connect(). The connect() library function has no facility to specify a time-out, but there is a way around this. The trick is put the socket into non-blocking mode first with:

fcntl(sockfd, F_SETFL, O_NONBLOCK);

This means that a call to connect() does not block, but immediately returns. In a loop, we then use the select() call to wait until some event happens on the socket, and for that we can set a timeout. In code, that looks (slightly simplified) like:

timeout.tv_sec = 0;
timeout.tv_usec = 200000;

while (1) {
        fd_set rset, wset, eset;

        FD_ZERO(&rset); FD_SET(sockfd, &rset);
        FD_ZERO(&wset); FD_SET(sockfd, &wset);
        FD_ZERO(&eset); FD_SET(sockfd, &eset);

        if (select(sockfd+1, &rset, &wset, &eset, &timeout) == 0) {
                return -2;
        }

        /* if our descriptor is ready break out */
        if (FD_ISSET(sockfd, &wset) || FD_ISSET(sockfd, &rset)) {
                break;
        }
}

Now we loop until the is either an error on the socket, or when select() notices an event on the socket that tells us that the connection has been made. I did not add a configuration setting to select the maximum timeout, as I consider that overkill. However, the value of 200ms should be adequate.

Bug fixed! Perhaps the next one should be a feature addition…