Creating the Listener

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.

Configuring the Aggregation Interval

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:

Shutting Down the Application

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.