7.3. Asynchronous Receiving

By default, a receiver retrieves a single message synchronously in response to a fetch() call. The receiver's capacity to prefetch messages is 0 by default.

When the receiver's capacity is set to a value greater than 0, the receiver will asynchronously retrieve up to that number of messages from the queue. This asynchronous retrieval is called prefetch, and it is enabled and controlled by setting the capacity property of a receiver.

Prefetching messages has two advantages:

Note two things about the available() method:

Prefetching is asynchronous, which means that you cannot rely on the number returned by a call to available() as an absolute indicator of the state of the queue. For example, calling available() immediately after setting the capacity of a receiver to something other than 0 is likely to return a value of 0 messages available. This does not necessarily mean that the queue has no messages, but rather that no prefetched messages are locally available yet.

Note also that the maximum value reported by the available method of a receiver with prefetching enabled will be the capacity of the receiver. The available() method reports the number of prefetched messages available, not the number of messages in the queue. If the number of available messages is less than the capacity of the receiver, however, you can infer that this is the number of messages in the queue, with the above caveat about the asynchronous nature of prefetching.