Skip to content

[12.x] Add withHeartbeat method to LazyCollection #56477

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: 12.x
Choose a base branch
from

Conversation

JosephSilber
Copy link
Contributor

@JosephSilber JosephSilber commented Jul 29, 2025

Adds a new withHeartbeat method to LazyCollection, which allows you to run a callback at regular time intervals while the collection is being lazily enumerated:

$collection
    ->withHeartbeat(CarbonInterval::minutes(5), function () {
        // ...
    })
    ->each(function ($item) {
        // ...
    });

Main use case

In long-running tasks such as batch processing reports, you may need to hold a lock to prevent concurrent execution. However, if the code unexpectedly fails to release the lock, you don't want it to persist indefinitely. A common strategy is to acquire a short-lived lock, and then periodically extend it while the task is still running.

Here's an example where we acquire a lock for 5 minutes, then reacquire it every 4 minutes (assuming a report never takes a full minute to generate):

$lock = Cache::lock('generate-reports', CarbonInterval::minutes(5));

$lock->acquire();

Reports::where('status', 'pending')
    ->lazy()
    ->withHeartbeat(CarbonInterval::minutes(4), $lock->reacquire(...))
    ->each($this->generateReport(...));

$lock->release();

Note: the locking logic above is simplified for clarity. It's essentially pseudo-code.

@shaedrich
Copy link
Contributor

I actually wasn't able to guess from the method name what exactly it would do. Maybe something like withInterval() would be more intuitive, named after JavaScript's setInterval()

@JosephSilber
Copy link
Contributor Author

This doesn't run at an interval on its own. It only triggers as you pull values from the list, indicating that it's still running.

heartbeat is the standard term for this.

https://en.wikipedia.org/wiki/Heartbeat_(computing)

@vadimonus
Copy link
Contributor

vadimonus commented Aug 1, 2025

You give a very specific example. If a cache is used for locking, there is nothing wrong with reacquire of lock in the method every; it will not cause slowdown. If another locking mechanism is used, where the process of re-acquiring the lock is long, then this is an even more specific case and a separate example is needed.

This can also lead to misunderstanding when reading the code. When looking at code from the example, it may seem that heartbeat will really be called every 4 minutes. But php is a synchronous language, and if the report generation is long, the next callback call can be in 4.5 minutes or in 10 minutes, or in hour.

Framework should not have methods with such unpredictable behavior. For example takeUntilTimeout and throttle methods are more predictable, takeUntilTimeout takes new element until timeout reached but do not promises that processing will finish before timeout.

For your special case is enough to use tapEach or takeWhile methods with very simplie logic. This will be more readable and more flexible.

Reports::where('status', 'pending')
    ->lazy()
    ->tapEach(function () {
       if ($time >= $lockReacquireTime) {
          $lock->reacquire();
          $reacquireTime = now()->addMinutes(4);
       }
    })
    ->each($this->generateReport(...));

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants