PreEmptive Analytics Win32 Client
 All Classes Files Functions Variables Typedefs Macros
Public Member Functions | List of all members
FlowController Class Reference

Controls the sending of messages to the server. More...

Public Member Functions

DLL_PACLIENT FlowController ()
 Create a default FlowController. More...
 
DLL_PACLIENT ~FlowController ()
 Dispose of a FlowController instance. More...
 
DLL_PACLIENT unsigned int GetGain () const
 Get the rate at which the interval should be changed in relation to the rate of messages. More...
 
DLL_PACLIENT size_t GetHighWater () const
 Get the point at which queued messages should be batched and transmitted. More...
 
DLL_PACLIENT size_t GetMaximumBatchSize () const
 get the maximum size a message batch can be, in bytes. More...
 
DLL_PACLIENT unsigned int GetMaximumInterval () const
 Gets the maximum amount of time that the transmitter should wait between checking the message queue. More...
 
DLL_PACLIENT unsigned int GetMaximumSequentialFailureCount () const
 Get the maximum number of sequential transmission failures before transmissions should be skipped. More...
 
DLL_PACLIENT size_t GetMinimumFailureCount () const
 Get the number of transmission attempts before a message is considered for deletion. More...
 
DLL_PACLIENT unsigned int GetMinimumInterval () const
 Get the minimum amount of time that the transmitter should wait between checking the message queue. More...
 
DLL_PACLIENT long long GetMinimumTimeToLive () const
 Get the time in seconds a message has been persisted before a message is considered for deletion. More...
 
DLL_PACLIENT size_t GetQueueSize () const
 Get the maximum number of messages that can be held in the queue. More...
 
DLL_PACLIENT unsigned int GetQuietGain () const
 Get the rate at which the interval should be changed when the queue is empty. More...
 
DLL_PACLIENT long GetRetryTimeout () const
 Get the number of milliseconds to wait before allowing transmissions after a series of sequential failures. More...
 
DLL_PACLIENT FlowControlleroperator= (const FlowController *other)
 Copy the values of another FlowController instance. More...
 
DLL_PACLIENT void SetGain (unsigned int value)
 Set the rate at which the interval should be changed in relation to the rate of messages. More...
 
DLL_PACLIENT void SetHighWater (size_t value)
 Set the point at which queued messages should be batched and transmitted. More...
 
DLL_PACLIENT void SetMaximumBatchSize (size_t maxSize)
 Set the maximum size a message batch can be, in bytes. If a batch exceeds this value it will be split into multiple batches. If a single message exceeds this size, it will be discarded. More...
 
DLL_PACLIENT void SetMaximumInterval (unsigned int value)
 Sets the maximum amount of time that the transmitter should wait between checking the message queue. More...
 
DLL_PACLIENT void SetMaximumSequentialFailureCount (unsigned int value)
 Set the maximum number of sequential transmission failures before transmissions should be skipped. More...
 
DLL_PACLIENT void SetMinimumFailureCount (size_t minimumFailures)
 Set the number of transmission attempts before a message is considered for deletion. More...
 
DLL_PACLIENT void SetMinimumInterval (unsigned int value)
 Set the minimum amount of time that the transmitter should wait between checking the message queue. More...
 
DLL_PACLIENT void SetMinimumTimeToLive (long long minimumTime)
 Set the time in seconds a message has been persisted before a message is considered for deletion. More...
 
DLL_PACLIENT void SetQueueSize (size_t value)
 Set the maximum number of messages that can be held in the queue. More...
 
DLL_PACLIENT void SetQuietGain (unsigned int value)
 Set the rate at which the interval should be changed when the queue is empty. More...
 
DLL_PACLIENT void SetRetryTimeout (long value)
 Set the number of milliseconds to wait before allowing transmissions after a series of sequential failures. More...
 

Detailed Description

Controls the sending of messages to the server.

The FlowController is used by the PAClient to control the when and how messages are handled. An instance of a FlowController can be passed into PAClient::ApplicationStart() but if one is not provided a default instance is used.
The FlowController defines how many messages can be queued for storage and when the messages are grouped into either a transmission to the server or stored offline.

Constructor & Destructor Documentation

DLL_PACLIENT FlowController::FlowController ( )

Create a default FlowController.

The Default Flow Controller implementation uses the following values:
  • QueueSize - 30 messages
  • HighWater - 20 messages
  • MaximumInterval - 30 sec
  • MinimumInterval - 1 msec
  • Gain - 66
  • QuietGain - 33
  • MaximumSequentialFailureCount - 3
  • RetryTimeout - 60 sec
Other properties of the FlowController are overridden by settings in the Configuration object and need not be set before passing the instance to PAClient::ApplicationStart().
DLL_PACLIENT FlowController::~FlowController ( )

Dispose of a FlowController instance.

Member Function Documentation

DLL_PACLIENT unsigned int FlowController::GetGain ( ) const

Get the rate at which the interval should be changed in relation to the rate of messages.

Returns
the rate at which the interval should be changed in relation to the rate of messages.
See Also
SetGain()
DLL_PACLIENT size_t FlowController::GetHighWater ( ) const

Get the point at which queued messages should be batched and transmitted.

Returns
the point at which queued messages should be batched and transmitted. It must always be greater than or equal to one and less than the queue size.
See Also
SetHighWater()
SetQueueSize()
DLL_PACLIENT size_t FlowController::GetMaximumBatchSize ( ) const

get the maximum size a message batch can be, in bytes.

Returns
the maximum size a message batch can be, in bytes.
See Also
SetMaximumBatchSize()
DLL_PACLIENT unsigned int FlowController::GetMaximumInterval ( ) const

Gets the maximum amount of time that the transmitter should wait between checking the message queue.

See Also
SetMaximumInterval()
DLL_PACLIENT unsigned int FlowController::GetMaximumSequentialFailureCount ( ) const

Get the maximum number of sequential transmission failures before transmissions should be skipped.

Returns
the number of sequential transmission failures before transmissions should be skipped.
See Also
SetMaximumSequentialFailureCount()
DLL_PACLIENT size_t FlowController::GetMinimumFailureCount ( ) const

Get the number of transmission attempts before a message is considered for deletion.

Returns
the number of transmission attempts a message is considered for deletion.
See Also
SetMinimumFailureCount()
DLL_PACLIENT unsigned int FlowController::GetMinimumInterval ( ) const

Get the minimum amount of time that the transmitter should wait between checking the message queue.

Returns
the minimum amount of time that the transmitter should wait between checking the message queue in milliseconds.
DLL_PACLIENT long long FlowController::GetMinimumTimeToLive ( ) const

Get the time in seconds a message has been persisted before a message is considered for deletion.

Returns
the time in seconds a message has been persisted before a message is considered for deletion.
See Also
SetMinimumTimeToLive()
DLL_PACLIENT size_t FlowController::GetQueueSize ( ) const

Get the maximum number of messages that can be held in the queue.

Returns
the maximum number of messages that can be held in the queue. This value will always be greater than two.
See Also
SetQueueSize()
DLL_PACLIENT unsigned int FlowController::GetQuietGain ( ) const

Get the rate at which the interval should be changed when the queue is empty.

Returns
the rate at which the interval should be changed when the queue is empty.
See Also
SetQuietGain()
DLL_PACLIENT long FlowController::GetRetryTimeout ( ) const

Get the number of milliseconds to wait before allowing transmissions after a series of sequential failures.

Returns
the number of milliseconds to wait before allowing transmissions after a series of sequential failures.
See Also
SetRetryTimeout()
DLL_PACLIENT FlowController& FlowController::operator= ( const FlowController other)

Copy the values of another FlowController instance.

Returns
this instance
DLL_PACLIENT void FlowController::SetGain ( unsigned int  value)

Set the rate at which the interval should be changed in relation to the rate of messages.

This is an value greater than zero and represents a rate of change in the interval time. It works like a percentage: a value of 50 indicates that half the distance between the current interval and the desired interval should be applied. Values greater than 100 are allowed.
Setting a value greater than 100 allows the transmitter to anticipate bursts of messages. This can reduce the possibility of dropped messages but can cause the transmitter to wake frequently and send smaller batches of messages to the server.
Setting a value less than 100 lets the transmitter conservatively adjust its wait time. This lets the transmitter send full batches of messages to the server but can lead to dropped messages if they are produced in rapid bursts.
Parameters
valueThe rate at which the interval should be changed in relation to the rate of messages.
DLL_PACLIENT void FlowController::SetHighWater ( size_t  value)

Set the point at which queued messages should be batched and transmitted.

This value is set automatically when the queue size is set but can be set independently.
Parameters
valuethe point at which queued messages should be batched and transmitted. It must always be greater than or equal to one and less than the queue size.
DLL_PACLIENT void FlowController::SetMaximumBatchSize ( size_t  maxSize)

Set the maximum size a message batch can be, in bytes. If a batch exceeds this value it will be split into multiple batches. If a single message exceeds this size, it will be discarded.

Parameters
minimumTimethe maximum size a message batch can be, in bytes.
DLL_PACLIENT void FlowController::SetMaximumInterval ( unsigned int  value)

Sets the maximum amount of time that the transmitter should wait between checking the message queue.

Parameters
valuethe maximum amount of time that the transmitter should wait between checking the message queue in milliseconds
DLL_PACLIENT void FlowController::SetMaximumSequentialFailureCount ( unsigned int  value)

Set the maximum number of sequential transmission failures before transmissions should be skipped.

If less than or equal to zero then failures do not cause transmissions to be skipped.
Parameters
valuethe number of sequential transmission failures before transmissions should be skipped.
DLL_PACLIENT void FlowController::SetMinimumFailureCount ( size_t  minimumFailures)

Set the number of transmission attempts before a message is considered for deletion.

Parameters
minimumFailuresthe number of transmission attempts a message is considered for deletion.
DLL_PACLIENT void FlowController::SetMinimumInterval ( unsigned int  value)

Set the minimum amount of time that the transmitter should wait between checking the message queue.

Parameters
valuethe minimum amount of time that the transmitter should wait between checking the message queue in milliseconds.
DLL_PACLIENT void FlowController::SetMinimumTimeToLive ( long long  minimumTime)

Set the time in seconds a message has been persisted before a message is considered for deletion.

Parameters
minimumTimethe time in seconds a message has been persisted before a message is considered for deletion.
DLL_PACLIENT void FlowController::SetQueueSize ( size_t  value)

Set the maximum number of messages that can be held in the queue.

If more messages are placed in the queue then the queue can hold then oldest messages will be discarded rather than transmitted or stored.
Parameters
valuethe maximum number of messages that can be held in the queue. This value must always be greater than two.
DLL_PACLIENT void FlowController::SetQuietGain ( unsigned int  value)

Set the rate at which the interval should be changed when the queue is empty.

This is similar to the way the gain works but is used when the previous interval has expired and there are no messages to be sent.
Setting smaller values lets the transmitter slowly reduce its wait time when responding to rapidly changing message frequency. This can reduce the possibility of dropped messages but can cause the transmitter to wake frequently and send smaller batches of messages to the server.
Setting larger values lets the transmitter quickly reduce its wait time after a burst of messages. This lets the transmitter send full batches of messages to the server but can lead to dropped messages if messages are produced in rapid bursts followed by quiet periods.
Parameters
valueThe rate at which the interval should be changed when the queue is empty. This value must be between one and 100.
DLL_PACLIENT void FlowController::SetRetryTimeout ( long  value)

Set the number of milliseconds to wait before allowing transmissions after a series of sequential failures.

If less than or equal to zero then retries are never attempted.
Parameters
valuethe number of milliseconds to wait before allowing transmissions after a series of sequential failures.