Re: Which exit code should --halt give?

[Martin d'Anjou]

On 15-05-02 06:26 AM, Ole Tange wrote:
> I have given much thought into the exit code of --halt 0 (i.e. --halt
> never), namely the number of failed jobs. I still believe that is the
> useful thing to return.

The count of failed jobs is useful up to a max of 255 jobs because the 
exit code rolls over at 255, it is an 8-bit number. Exit 256 is the same 
as exit 0, which means "no error". If the user submits more than 256 
jobs, the count of errors is not reliable anymore, so exiting with the 
count of errors is only meaningful in the context of the user submitting 
255 jobs or less, and only the user knows their context after GNU 
parallel has exited.


> I have given some thought into the exit code of --halt 1/--halt 2
> (i.e. --halt soon,fail=1/--halt now,fail=1), namely the exit code of
> the failing job. I think this is useful, too.
>
> I am, however, not sure what the useful exit code should be for:
>
> --halt soon,success=1 == --halt -1
> --halt now,success=1 == --halt -2

This is not a scenario I expect to use, but I can suggest:
Exit with 0 if there is at least one success because it meets the 
expectation that was set, otherwise exit with non-zero.

> --halt soon,fail=XX% == --halt XX%
> --halt now,fail=XX%

An analogy to the physical world can help visualize this scenario. Say 
you are doing a destructive test on a batch of samples. Suppose it is a 
compression test on some new building material. You submit all the 
samples to the same test. If they all pass the test, things are good 
(exit 0). If any of them fail the test, then the testing as a whole is a 
failure (exit 1). The reason you don't halt at the first failure but 
rather at the XX% failure is that you want to halt the testing with more 
than one failure to do comparative failure analysis. If the failure rate 
never exceeds XX% by the time the samples are all used up, it only means 
the comparative failure analysis won't have with as many samples to 
study, but the test as a whole is still a failure (so still exit 1). And 
to be complete, if the failure rate does exceed XX%, then the test as a 
whole is still a failure because some samples did not pass the test (so 
exit 1).


> --halt soon,success=X (X>1)
> --halt now,success=X (X>1)

This is not a scenario I expect to use, but I can suggest:
Exit with 0 if there is at least one success, otherwise exit with non-zero.

I think one might want to use that mode of operation when they are 
looking for more than one valid hypotheses in a set of hypotheses. So 
they should be told whether the success they expected (success=X) was 
met (exit 0) or not met (exit non-zero).

> --halt soon,fail=X (X>1)
> --halt now,fail=X (X>1)

Same as failure with percentage above.

> --halt soon,success=XX%
> --halt now,success=XX%

Same as with success=X above.

Hope this helps,
Martin