Threading When Receiving Messages in the PubSub+ JCSMP API

When receiving published messages with the PubSub+ JCSMP API, the context uses a processing thread to read messages off the socket, parse them, and then, depending on whether a synchronous or asynchronous mode is used, enqueue the messages for delivery or consumption, or perform customer notification and message dispatch.

Client applications can use one of the following modes to receive published messages:

  • Asynchronous

    Client applications can use the Java, Java RTO, C, and .NET APIs to receive published messages asynchronously. Refer to Receiving Messages Asynchronously.

Receiving Messages Asynchronously

A client application can use the PubSub+ JCSMP API to receive messages in an asynchronous manner. That is, when messages are available, they are automatically sent (“pushed”) to a message callback or message delegate interface from the API to the client application.

When receiving messages asynchronously, the context uses a processing thread for consumer notification and dispatching the queued messages to consumers; all callbacks from the API to the application, such as message receive callbacks, event callbacks, and timer callbacks, run from a context thread.

When a client application is using asynchronous transacted sessions, messages are dispatched from one or more transacted session dispatcher threads. Either a single transacted session dispatcher thread that is bound to the context (this is the default) or separate transacted session dispatcher threads that are that are bound to each transacted session can be used. For more information, refer to Using Local Transactions in the PubSub+ JCSMP API.

By default, the PubSub+ JCSMP API API’s context uses one thread to read messages off the socket, parse them, and then enqueue them on the consumer notification dispatcher queue. It uses another thread for consumer notification and dispatching the queued messages to consuming client applications.

The maximum number of messages that can be queued by the context per session before they are delivered to consumers is as follows:

  • Direct messages—5,000
  • Guaranteed messages—The maximum number of messages permitted by each flow’s Guaranteed message window size. (A Guaranteed message window size limits the number of messages that the API can receive before it must return an acknowledgment to the event broker that it received the messages in the window.)

The consumer notification dispatcher queue that is used to asynchronously notify consumers of messages and exceptions through an XMLMessageListener can be resized, if necessary. This queue should be large enough to buffer the maximum number of notifications that are generated for all consumer flows (Guaranteed and Direct messages) in all of the sessions in a context. If an XMLMessageListener does not always return control quickly and the consumer notification dispatcher queue fills up, the API thread attempting to enqueue notifications to this queue can be temporarily blocked and can cause messages to queue on the event broker.

To resize the consumer notification dispatcher queue, call JCSMPGlobalProperties.setConsumerDispatcherQueueSize().

Global properties may only be set before any sessions have been created from the JCSMPFactory.

The figure below shows the context threads that are used to receive messages asynchronously through the PubSub+ JCSMP API.

For ultra low latency applications, you can enable the MESSAGE_CALLBACK_ON_
REACTOR session property to reduce message latency. When this session property is enabled, messages delivered asynchronously to an XMLMessageListener are delivered directly from the I/O thread instead of from the consumer notification and dispatch thread. Although enabling this session property reduces message latency, it also decreases the maximum message throughput.

An application using the MESSAGE_CALLBACK_ON_REACTOR session property must not call any blocking methods in the onReceive() callback; doing so could cause the application to deadlock.

The figure below shows shows the context thread that is used to receive messages asynchronously through the PubSub+ JCSMP API when the MESSAGE_CALLBACK_ON_REACTOR session property is enabled.

Receiving Messages Synchronously

When receiving messages in a synchronous manner, the client application uses explicit receive calls to retrieve messages from the message queues that the API uses for each consumer. When receiving messages synchronously, the client application provides the threads that “pull” the enqueued messages from the API.

PubSub+ JCSMP API

To receive messages, the client application must use start() to enable receiving messages from the event broker, and then use synchronous receive(...) calls to receive the next available message. The receive methods can manage the potential blocks by waiting indefinitely until there are messages, not waiting when there are no messages (that is, immediately timing out when there are no messages), or timing out after a set period of time when there are no messages.

The figure below shows shows the context thread and application threads that are used when messages are received synchronously through the PubSub+ JCSMP API.