The first step in using the System Manager Listener C++ API is to instantiate the Listener object to listen for connections from Managers. The application should only create one Listener object and once created, the Listener must exist for the lifetime of the application. The syntax for instantiating the Listener is as follows:
Listener listener("appName", "appVersion",
[optional] heartbeatObject, [optional] ListenerOn);
The appName and appVersion
parameters are
strings which provide the name and version number of the application. The Listener
constructor is overloaded to allow these strings to be passed as Unicode (const
wchar_t *), where both may contain any printable UTF-8 characters excluding
the newline character.
NOTE Throughout this document, wherever a const char * argument is specified, const wchar_t * arguments are also accepted. Regardless of which declaration is implemented, an internal copy of the string is made and the application does not need not maintain the pointer once the constructor has finished execution.
The optional heartbeatObject
parameter
provides the Listener with the ability to handle health status requests or Custom
Messages received from connected Managers. To obtain the default behavior, developers
may use a PCHcallable object. When no value
is specified for the heartbeatObject
parameter, then a PCHcallable
object is automatically created. For more information about implementing this
class, see Supporting Communication
from Managers.
The ListenerOn
parameter is an optional Boolean value (default
is true), which indicates whether the Listener object should actually be enabled
to create background threads, open sockets, write to log files, and so on. When set
to false, the application can easily "turn off" this Listener functionality
if necessary. However, even when the Listener is not enabled, objects are still
created and can be accessed in the usual manner from the Listener APIs.
The aggregation interval is the length of time over which each summary block of performance data is accumulated by the Listener. At the end of each aggregation interval, the Listener computes a summary block (basically, a snapshot of the current counter values), sends this summary to any Managers that have requested automatic updates, and then resets the min and max values associated with the Accumulators. This summary block is also added to a running history maintained by the Listener, which allows newly-connecting Managers to request information about recent application activity.
Although an application may configure the aggregation interval, the value is normally left to the default or specified by the Manager. The interval value can be specified in the following ways:
output_count
and output_interval
configuration parameters. For more information
about modifying these parameters, see Configuring
the Listener.listener->setInterval(interval);
When the application is going to exit, it may call the shutdown member function of the Listener to record any partial summary blocks and guarantee that the final gathered performance data will not be lost:
listener->shutdown();
However, it is not necessary for the application to directly call shutdown, as the destructor for the Listener object indirectly calls shutdown.
CAUTION If the application exits without
calling either the destructor of the Listener or the shutdown function, then
the most recent performance data which was being added to the current summary
block will be lost, but there will be no other negative consequences.