Issue-42: Provide a safe way to halt the bulk task (2.x)

[renatonascalves]

Summary

Fixes #42

This pull request introduces functionality to safely halt a bulk task and resume it later from the same position in the database. This enhancement avoids the need to let the bulk task run unnecessarily or restart from the beginning when resuming.

Description

Currently, once a bulk task begins, it processes the entire database, invoking the callable for each item. However, there is no built-in way to halt the task and resume later at the same position. This PR addresses that limitation by:

• Allowing the callable to return false to signal the task to halt early.
• Ensuring the cursor (min_id) is updated to reflect the last processed item when halting.
• Adding logic to cleanly pause execution while maintaining the integrity of after-task logic.

Additionally, unnecessary parameters in test methods have been removed to simplify the codebase, and new test cases have been introduced to validate the halt-and-resume functionality.

Motivation and Context

This change is motivated by a real-world use case where a bulk task was designed to delete items from a database. The client requested the ability to stop after deleting a specific number of items to review the impact of the deletions before proceeding further. Previously, stopping the task early required letting the rest of the bulk task run unnecessarily or restarting it from the beginning, which was inefficient and error-prone.

How Has This Been Tested?

• Unit tests:
  • A new test method, test_halt_task, was added to ensure the bulk task can be halted and resumed correctly.
  • Existing tests were updated to reflect the changes in callable behavior and cursor updates.
• Manual testing:
  • Tested with varying database sizes and callable implementations to ensure the feature works as expected.
  • Verified that halting and resuming maintains the correct position and state.

Screenshots (if applicable)

N/A

Types of changes

• New feature (non-breaking change which adds functionality)
• Bug fix (non-breaking change which fixes an issue)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have added tests to cover my changes.
• All new and existing tests passed.

[mboynes]

While I didn't fully review the PR, I skimmed it for the approach. I think this was a fine way to go, and certainly reasonable from a DX perspective. I do think it's a tad risky from a backwards-compatible perspective, as someone's callable might innocuously be returning false right now, and this would break that.

I'll offer another potential approach to this problem that doesn't have as pleasant of a DX, but it would (a) be backwards compatible, (b) be more explicit, and (c) would open up an opportunity to safely handle interrupt signals. If instead of checking for the return value of the callable, the loop could instead live within a try-catch block and we could introduce a specific exception class like Gracefully_Halt_Bulk_Task_Exception. A callable would then throw that exception if it wanted to halt command progress but still update the cursor. Similarly, we could intercept an interrupt command (ctrl-c) and throw that same exception, so a bulk task could then be safely aborted. (I suspect that would take a little more work than I'm laying out, because we would ideally let the callable finish before interrupting it... not sure if that's even doable, but that's a problem for another day)