Flow control

A client application rapidly making thousands of calls to the Diffusion™ server might overflow the internal queues for the client, which results in that client session being closed. Flow control automatically protects against these queues overflowing by progressively delaying messages from the client to the Diffusion server .

Supported platforms: Android™ , Java™ , .NET, and C

The flow control mechanism is a feature of the Diffusion client libraries that works automatically to protect the following internal queues for an individual client from overflowing:

The outbound queue on the client where messages are queued to be sent to the Diffusion server
The queue on the Diffusion server where responses to service requests are queued.

If these queues overflow, the client session is terminated.

Flow control is intended to benefit those clients that send a lot of data to the Diffusion server – for example, updates to publish to topics. Usually, these clients are those located in the back-end of your solution that perform control functions.

When is flow control enabled?

The client determines whether to enable flow control and the amount of delay to introduce into the client processing based on a calculated value called back pressure. Back pressure is calculated using the following criteria:

Depth of the outbound client queue
The number of pending responses to service requests
Whether the current active thread is a callback thread

Back pressure can have a value between 0.0 and 1.0. 1.0 is the maximum amount of back pressure. The method used to calculate back pressure might be subject to change in future releases.

Flow control introduces sleeps into the client processing. The length of these sleeps depends on the value of the back pressure. The maximum amount of delay introduced into client processing by flow control is 100 ms. The amount of delay introduced by flow control might be subject to change in future releases.

The flow control behavior of a client cannot be configured.

How to tell that flow control is enabled

When flow control is enabled for a Android , Java , or .NET client, the client logs messages at DEBUG level. The client logs each time a delay is introduced. The log message has the following form:

2016-09-26 11:15:48,344 DEBUG [PushConnectorPool-thread-18] c.p.d.f.SleepingFlowControl(apply) - pressure=1.0 => sleep for 100 ms

The log message includes the current back pressure and the length of delay introduced.

The C client does not log its flow control behavior.

Actions to take

Diffusion clients can occasionally become flow controlled in response to very heavy load or unusual network conditions. However, if your clients are constantly being flow controlled, your Diffusion solution might not be correctly configured for the traffic load.

Consider taking the following actions:

In your client design, ensure that if you have many requests to make to the Diffusion server that these requests are made from an application thread instead of a callback thread. Less flow control is applied when the active thread is a callback thread. For more information, see Best practice for developing clients.
Ensure that your Diffusion server can handle the incoming messages from the clients. The default memory configuration might be causing the JVM running the Diffusion server to spend a lot of time in GC. For more information about tuning your JVM, see Memory considerations.
Increase the maximum queue size on the connector your client uses. This can be configured for individual connectors in the Connectors.xml configuration file or as a default value for all connectors in the Server.xml configuration file. For more information, see Connectors.xml and Server.xml.