In mongodb/mongo-php-driver#932 for PHPC-1123, I proposed we deprecate Cursor::isDead(), which returns the inverse of mongoc_cursor_is_alive(), and introduce a new method that directly wraps mongoc_cursor_more() and is documented similarly. Note that is_alive() is just a deprecated alias of more().

My goal there was to introduce a better-named method with clearer documentation; however, in this comment I talked about how the best we can do in any driver is report whether a cursor potentially has more data. The only case where more() returns false is when there are no more results in the local buffer (i.e. most recent batch) and the cursor ID is zero. To that end, perhaps it makes sense to leave isDead() in place and simply improve its documentation to describe all of the cases outlined in that comment:

The cases where a cursor may have more data are as follows:

• We know there are additional documents in the current batch (buffered on the client side). Iterating will fetch a document from our local buffer.
• There are no additional documents in the current batch, but we have a cursor ID. Iterating will request the server for more documents, at which point we will either:
  • Receive a batch containing more documents and the cursor ID will be kept open. This is common to iterating through a large result set.
  • Receive a batch containing more documents and the cursor ID will be zero, which signifies that we've received the final batch from the server (i.e. cursor is closed server-side)
  • Receive an empty batch from the server, but the cursor ID is kept open. This tells us we should consult the server for more documents later (common in tailable cursors).
  • Receive an empty batch from the server and the cursor ID will be zero. AFAIK, this is the only case where we are assured that there are not potentially more documents (i.e. more() returns false).

If we look at the libmongoc source, we can see that isDead() is succinctly described as the cursor being in either a "failed" or "done" state.