Batch reads use a consume-on-confirm contract, so that the module only removes an item from the backend after the consumer has confirmed that it processed the item, for example by sending it to the cloud successfully. A typical session runs as follows:
- The consumer publishes
STORAGE_BATCH_REQUESTwith a non-zerosession_id. - The Storage module responds with
STORAGE_BATCH_AVAILABLE, withdata_lenset to the number of items available, and primes the pipe with the head item. If there is no data, it sendsSTORAGE_BATCH_EMPTY, and you must still close the session. - The consumer calls
storage_batch_read()to read the head item. This call does not remove the item from the backend. - After processing the item, the consumer publishes
STORAGE_BATCH_CONSUMEwith the matchingsession_idand thedata_typeof the item. The Storage module removes the head item and primes the next one in the pipe. - Steps 3 and 4 repeat until
storage_batch_read()returns-ENODATA, or until the consumer decides to stop. - The consumer publishes
STORAGE_BATCH_CLOSEto end the session.
If the consumer reads without consuming, storage_batch_read() repeatedly
returns the same head item. If a STORAGE_BATCH_CONSUME arrives with an
unknown or mismatched data_type, the Storage module aborts the session with
STORAGE_BATCH_ERROR to avoid silent stalls.