= NAME =
allocate_next_batch_id

= SYNOPSIS =
Allocate and return the next global batch id for the Fuego system.

= DESCRIPTION =
This function reads the global batch_id file for Fuego, and returns it.
It then increments the number and saves it back to the file for the next
allocation operation.

The global batch_id is stored in $FUEGO_RW/logs/next_batch_id, and is
global over all tests.

Using this function will make the batch_id a monotonically increasing
decimal number.

Callers of this function are encouraged to use this global number for
batch tests, but to also prefix the number with a test-specific string,
so that batch_ids are easier for humans to associate with their related
batch tests. 

= EXAMPLES =
Here are some sample invocations:
{{{#!YellowBox
FUEGO_BATCH_ID="prefix-$(allocate_next_batch_id)"
}}}

= ENVIRONMENT and ARGUMENTS =
Environment variables used:
 * FUEGO_RW

= RETURN =
Returns non-zero on error.

= SOURCE =
Located in ''scripts/functions.sh''

= SEE ALSO =
 * [[Using Batch Tests]], [[function_run_test|run_test]]