[CDRIVER-2594] Update docs for cursor_is_alive and consider deprecating Created: 05/Apr/18  Updated: 28/Oct/23  Resolved: 15/Apr/18

Status: Closed
Project: C Driver
Component/s: None
Affects Version/s: None
Fix Version/s: 1.10.0

Type: Task Priority: Major - P3
Reporter: Kevin Albertson Assignee: Kevin Albertson
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Related
is related to CDRIVER-2604 Remove mongoc_cursor_is_alive Backlog

 Description   

CDRIVER-1221 explains in this comment that mongoc_cursor_is_alive should return true until mongoc_cursor_next returns NULL.

The docs for mongoc_cursor_is_alive say

Checks to see if a cursor is in a state that allows contacting a server to check for more documents. Note that even if false, there may be documents already retrieved that can be iterated using mongoc_cursor_next().

The docs don't match the behavior. When the last batch is returned (with a cursor id of 0) we know we won't be contacting the server again, yet mongoc_cursor_is_alive will continue to return true (shown in this test).

The current implementation is consistent with older behavior, so I don't think we should change it. However, we should update the documentation and consider deprecating it in favor of mongoc_cursor_more, which should behave the same (the done flag is set when the cursor id is 0 and there are no documents left in the last batch). As a sanity check, I replaced all calls of mongoc_cursor_is_alive with mongoc_cursor_more to verify tests passed.



 Comments   
Comment by Githook User [ 19/Apr/18 ]

Author:

{'email': 'kevin.albertson@10gen.com', 'username': 'kevinAlbs', 'name': 'Kevin Albertson'}

Message: CDRIVER-2594 remove cursor_is_alive from tests
Branch: master
https://github.com/mongodb/mongo-c-driver/commit/59dc452311db001ea6a742692a0be0b4614d428e

Comment by Githook User [ 10/Apr/18 ]

Author:

{'email': 'kevin.albertson@10gen.com', 'name': 'Kevin Albertson', 'username': 'kevinAlbs'}

Message: CDRIVER-2594 deprecate cursor_is_alive
Branch: master
https://github.com/mongodb/mongo-c-driver/commit/1a8a44e214d37b2ceabc3b0f773e5bdd79837664

Generated at Wed Feb 07 21:15:43 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.