Batch reads use a consume-on-confirm contract so that an item is only removed from the backend after the consumer has confirmed it was processed (for example, successfully sent to the cloud). A typical session looks like this:
- 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. - Consumer calls
storage_batch_read()to read the head item. This call does not remove the item from the backend. - After the item has been processed, 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-EAGAIN, or until the consumer decides to stop. - 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.