Doc about cronjob locking is unclear

[pquerner]

Note: I have not used this project yet, this is just an observation of the README.md

I find it difficult to understand how this project can help you with locking cronjobs, therefore I'd like a more advanced cronjob example in the README file.

Ie. whats a "resource" (without looking at the src of that factory class)

[mathroc]

I suppose you've seen this part of the readme https://github.com/texthtml/php-lock#using-lock-for-crontabs ?

'protected resource' is just a string to identify the cron you want to lock, if process is started with a lock with the same identifier it will be locked. is this what's unclear ?

[pquerner]

Yes. That you call it resource but use it as a identifier. That could just be called identifier then, no?
I mean, maybe thats just me.

[mathroc]

It identifies a resources that the cron will operate on and should be locked on, eg:

// invoices_aggregation_report.php

$lock = $factory->create('invoices-aggregation-report', 'process 1');

$lock->acquire();

foreach ($invoices as $invoice) {
  $invoiceReport->add($invoice);
  $invoice->saveToDatabase();
}

a cron could also lock multiple resources in the same way:

$invoicesReportLock = $factory->create('invoices-aggregation-report', 'process 1');
$invoicesReportLock->acquire();


$usersAccountLock = $factory->create('invoices-aggregation-report', 'process 1');
$usersAccountLock->acquire();

so each cron can declare which resources he wants to himself

[pquerner]

If "invoices-aggregation-report" is still running when the second cron comes around, it would fail then, yes?
Whats the second parameter "process 1" ?

I mean, that all could be documented better. What the method takes as arguments and why, with more 'real life' examples like you posted above.

[mathroc]

yes it would fail, this part is in the readme:

When process 1 is running and we start process 2, an Exception will be thrown: "Could not acquire exclusive lock on protected resource" and if the factory was configured with a \Psr\Log\LoggerInterface, messages explaining what happend would be logged:

and the second parameter is used for the logs, from the readme:

process 1: exclusive lock acquired on protected resource
process 2: could not acquire exclusive lock on protected resource
process 2: lock released on protected resource

I probably won't add more documentation myself as I'm not actively working on this since it's mostly stable but feel free to open a Pull Request once you figure out a better way of explaining how it works (reading the phpspec tests & source code can help, it's a qucik read)