mysqli_poll() - what's the third parameter for?

Question

In the absence of any documentation beyond a function prototype I'm struggling to find what the the third parameter to the mysqli_poll() function is.

int mysqli_poll ( 
     array &$read , 
     array &$error , 
     array &$reject , 
     int $sec 
     [, int $usec ] )

Looking at the (C) source code, it appears to populate the $reject array with resources where...

CONN_GET_STATE((*p)->data) <= CONN_READY 
   || CONN_GET_STATE((*p)->data) == CONN_QUIT_SENT

Does this mean that the connection to the server is shutting down / shutdown?

Something else?

Should it be pre-poplulated with the resources to check for disconnection? Or will they be added automatically from $read and $error?

Answer 1

The arrays are bound to the select() system call.

As you see here: http://lxr.php.net/xref/PHP_5_5/ext/mysqlnd/mysqlnd.c#1384

So, yes, according to select(2) man documentation:

Select() examines the I/O descriptor sets whose addresses are passed in readfds, writefds, and errorfds to see if some of their descriptors are ready for reading, are ready for writing, or have an exceptional condition pending, respectively.

(writefds is here not important, it is ignored in the implementation)

The $read or $error arrays are allowed to be empty if the other is filled with mysqli objects.

$read has to be an array with mysqli objects you want to poll.

$error has to be an array with mysqli objects you want to check for extraordinary data.

As you see from http://lxr.php.net/xref/PHP_5_5/ext/mysqlnd/mysqlnd_enum_n_def.h#322 and http://lxr.php.net/xref/PHP_5_5/ext/mysqlnd/mysqlnd.c#1228, everything that doesn't match <= CONN_READY || == CONN_QUIT_SENT implies CONN_QUERY_SENT, CONN_SENDING_LOAD_DATA, CONN_FETCHING_DATA, CONN_NEXT_RESULT_PENDING (i.e. data is not yet ready to be fetched; names should be self-explaining) won't be added to the ready array == will be $rejected:

$rejected can be anything when you pass it to the function; it'll be overwritten with an array with the entries in $read which aren't yet ready to be read.

Answer 2

I believe that's where the rejected threads end up.

See this example: https://svn.osgeo.org/mapguide/sandbox/rfc94/Oem/php/ext/mysqli/tests/mysqli_poll.phpt