How to use CursorId?

[petr-buchin]

As far as I understand, the only way to use \MongoDB\Driver\CursorId instance is to get it's string representation.
But string representation of any CursorId instance is the same - "0".
For example:

$manager = new \MongoDB\Driver\Manager();

$query  = new \MongoDB\Driver\Query([]);
$cursor1 = $manager->executeQuery('test.test', $query);

$query2 = new \MongoDB\Driver\Query(['foo' => 'bar']);
$cursor2 = $manager->executeQuery('test.test2', $query2);

var_export((string) $cursor->getId()); // "0"
var_export((string) $cursor2->getId()); // "0"
(string) $cursor->getId() === (string) $cursor2->getId(); // true

Is it a bug, or \MongoDB\Driver\Cursor::getId() should not identify cursor uniquely? If latter, could you please explain, what is this method for and could you give an example of it's usage? Unfortunately documentation for this method is not very helpful.
I need this because I want to cache cursor instances in array by using some unique identificator as a key in array, but I don't know, whether I should use Cursor::getId() method or simply \spl_object_hash($cursor).

Thanks in advance!

[jmikola]

A Cursor object will only report an ID if the cursor is still open on the server. In your example, the query returns all of its results in the first batch, so no cursor is left open on the server and the ID is empty. Consider:

<?php

$manager = new \MongoDB\Driver\Manager();

try {
    $manager->executeCommand('test', new MongoDB\Driver\Command(['drop' => 'test']));
} catch (Exception $_) {}

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1]);
$bulk->insert(['x' => 1]);
$bulk->insert(['x' => 1]);
$manager->executeBulkWrite('test.test', $bulk);

$query = new \MongoDB\Driver\Query([], ['batchSize' => 2]);
$cursor = $manager->executeQuery('test.test', $query);
foreach ($cursor as $_) {
    var_dump($cursor->getId());
}

This will output something similar to:

object(MongoDB\Driver\CursorId)#8 (1) {
  ["id"]=>
  int(33133922541)
}
object(MongoDB\Driver\CursorId)#7 (1) {
  ["id"]=>
  int(33133922541)
}
object(MongoDB\Driver\CursorId)#9 (1) {
  ["id"]=>
  int(0)
}

While the cursor is active on the server, you can use its ID to kill it via the killCursors command in MongoDB 3.2+. Earlier versions of MongoDB require the OP_KILL_CURSORS wire protocol message (the message is deprecated but can still be used on newer versions). The legacy driver had a MongoClient::killCursor() method to issue the OP_KILL_CURSORS message, but we decided to not to add a similar API in the new driver. If you watch the mongodb.debug trace logs while killing a cursor with an ID, you'll notice that libmongoc sends a kill command for it (or OP_KILL_CURSORS on older servers). This is to prevent the driver from leaving an abandoned cursor open on the server.

The other intention of CursorId was to ensure that users on 32-bit platforms could issue a killCursors command if necessary, since cursor IDs are 64-bit integers and generally fall outside of the 32-bit range. That said, this would require PHPC-587 (ensuring CursorId objects serialize to BSON as 64-bit integers), which is not yet implemented. To date, no users have reported issues with killing cursors so we've not prioritized the issue.

One more thought on the subject: I agree that it's not ideal for Cursor::getId() to return a CursorId object with an empty value. The driver has no notion of an empty cursor, as we get that ID directly from libmongoc, which uses 0 to represent a closed cursor. I suppose we could check for that and have Cursor::getId() conditionally return null, but that force users to check the return value before using it. Another option might be adding an isEmpty() method on the CursorId class. That's assuming checking for (string) $cursorId === '' is problematic for folks :)

or simply \spl_object_hash($cursor).

Note that SPL object hashes are only unique provided the object is still in memory. They can be reused and lead to collisions within the same PHP process. See doctrine/mongodb-odm#1017 for one case.

[petr-buchin]

@jmikola , again, a very helpful and detailed answer. Thank you!

Note that SPL object hashes are only unique provided the object is still in memory. They can be reused and lead to collisions within the same PHP process.

I'll check my code to ensure that there is no possible bug with collisions :)

Also, I think it would be a great feature in ODM to save all CursorId instances and then at the end of request kill cursors, that are left open on a server. Or, maybe it's even better to throw an exception if cursor is left open at the end of request - it means user did not specified limit or specified wrong limit.

[jmikola]

Also, I think it would be a great feature in ODM to save all CursorId instances and then at the end of request kill cursors, that are left open on a server.

libmongoc already does this in _mongoc_cursor_destroy(), which we invoke when a MongoDB\Driver\Cursor object is garbage collected. This is what I was alluding to in my last post where I mentioned viewing the mongodb.debug trace logs to see libmongoc kill a cursor with a non-zero ID.

[petr-buchin]

If you watch the mongodb.debug trace logs while killing a cursor with an ID, you'll notice that libmongoc sends a kill command for it (or OP_KILL_CURSORS on older servers).

I did not understand this sentence correctly. I thought this is up to user to send killCursors command in a new driver, and you mentioned mongodb.debug as a way to see what is actually sent to the server when \MongoClient::killCursor() is called - OP_KILL_CURSORS wire protocol message or killCursors command :)

libmongoc already does this in _mongoc_cursor_destroy(), which we invoke when a MongoDB\Driver\Cursor object is garbage collected.

That's cool!

[jmikola]

MongoClient::killCursor() only issues the legacy OP_KILL_CURSORS wire protocol message. In the current driver, libmongoc's function to destroy a cursor will issue OP_KILL_CURSORS or the killCursors command based on the server version (if it thinks the cursor is still open on the server). There is no need for users to manually kill cursors in the new driver.