7.3. Asynchronous Receiving


7.3.1. Asynchronous Message Retrieval (Prefetch)

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:
  • Prefetched messages are available locally when requested by the application, without the overhead of a synchronous call to retrieve a message from the broker.
  • A receiver with prefetching enabled has an available() method that can be invoked to determine how many prefetched messages are available.
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.
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.