Creating Objects to Gather Performance Data

Once a Listener object has been instantiated, the application will begin to automatically record various system information, such as CPU load, disk and network I/O, as well as communications from connected Managers. The application may expose its performance data using four different categories:

In addition to these objects, Custom Messages are created at the top level of the Listener and are communicated the moment that recordCustomMessage is called.

Event and Meter objects may either be created at the top level of the Listener or logically grouped as subordinates in a Container object (which is always created at the top level of the Listener using the lookupContainer constructor). They may be created using the lookupEvent or lookupMeter constructors or via the new operator. Accumulator objects are always created as subordinates of Events using the lookupAccumulator constructor. Custom Messages are always created at the top level of the Listener using the recordCustomMessage constructor.

The lookupObjectType member functions will create the appropriate object only when that object does not already exist. If the object already exists, the existing object is returned. In addition, the application should not call delete on any objects returned by these functions.

Naming and Locating Objects in the Listener

The application creates each of these object types by specifying a unique name for the object which is assumed to be related to a concept or operation in the application, such as a counter for "Documents Created". Through overloaded member functions, the name may be specified either as a UTF-8 or Unicode string (internally translated to UTF-8). The names for any of these objects may consist of any sequence of printable characters excluding the newline character. In addition, an internal copy for each string is made and the application does not need not maintain the pointer once the lookupObjectType constructor has returned.

Once an object has been created, a pointer to the underlying object is available for the lifetime of the Listener. Internally, hash tables are used to map the unique names specified at object creation time to the actual created objects. By calling the lookupObjectType constructor and passing the same arguments as when an object was created, the application may obtain a pointer to the desired object whenever necessary. Therefore, the application should not maintain a separate lookup table. However, the application should retain a copy of the returned pointers and reuse them to reduce the overhead of performing the lookup operation. Depending on the structure of the application, this might be accomplished through the use of global variables, or by adding new member variables to objects associated with operations within the application.