OW32::CPerfData Class Reference

Performance data helper. More...

#include <PerfData.h>

List of all members.

Public Types
typedef DWORD	ObjectId
	Opaque object id type.
typedef DWORD	CounterId
	Opaque counter id type.
typedef DWORD	InstanceId
	Opaque instance id type.
enum	{ PERF_COUNTER_STORAGE = sizeof(__int64) }
	This is the amount of storage allocated for each counter The only misfit would be strings, but they don't work in perfmon anyway (I tried it!).
Public Member Functions
	CPerfData (LPCWSTR appName)
	Constructor that takes the name of the application.
	~CPerfData ()
	Destructor for cleanup.
void	addObject (CPerfObject *object)
	Add a performance object, generally initiated by the PERF_DATA_XXX macros.
CPerfObject *	getObjectById (ObjectId objectId)
	Helper function to return a CPerfObject from the it's object id.
DWORD	collect (LPWSTR values, LPVOID *ppData, LPDWORD pBytes, LPDWORD pcObjectTypes)
	Collect performance data for the given objects into the given buffer.
void	activate (bool fApplication)
	Set the peformance data up.
void	deactivate ()
	Disable performance data collection and free allocated resources.
void	install (LPCTSTR perfCollectorPath)
	Install registry entries for the performance data.
void	uninstall ()
	Remove registry entries for the performance data.
InstanceId	addInstance (ObjectId objectId, LPCWSTR name, ObjectId parentObjectId=0, InstanceId parentInstanceId=0)
	Add a named instance to the given object.
InstanceId	addInstance (ObjectId objectId, LONG uniqueID, ObjectId parentObjectId=0, InstanceId parentInstanceId=0)
	Add an instance of the given object identified by a unique ID The uniqueID cannot be PERF_NO_UNIQUE_ID.
void	removeInstance (ObjectId objectId, InstanceId instanceId)
	Remove the given instance of the given object.
__int64 *	getCounter64 (ObjectId objectId, CounterId counterId, InstanceId instanceId=0)
	Get a 64-bit pointer to the storage for the given counter.
LONG *	getCounter32 (ObjectId objectId, CounterId counterId, InstanceId instanceId=0)
	Get a 32-bit pointer to the storage for the given counter.
BYTE *	getCounter (ObjectId objectId, CounterId counterId, InstanceId instanceId=0)
	Get a BYTE* pointer to the storage for the given counter.
bool	lock (DWORD timeout=INFINITE)
	Lock object instances so that may be manipulated or read safely.
void	unlock ()
	Unlock object instances.

---

Detailed Description

Performance data helper.

---

Constructor & Destructor Documentation

OW32::CPerfData::CPerfData (  LPCWSTR  appName  )

Constructor that takes the name of the application. The name of the application is used to form the HKLM which stores the appropriate performance library information

---

Member Function Documentation

void OW32::CPerfData::activate (  bool  fApplication  )

Set the peformance data up. This creates the shared storage section and the object/counter definitions. Called to activate performance data collection. Parameters: fApplication  Set if the caller is the application that generates the performance data. In all cases, the shared section will exist after a successful call, but if the application is not running then typically you will not want perfmon to show the counters. deactivate() or the destructor takes note of this, and clears the flag that allows the performance object to be shown. You can show the counters all the time by always setting the application flag. Throws CPerfDataException on error. For the perflib Collect function, you can extract the Win32 error code and return it.

InstanceId OW32::CPerfData::addInstance (  ObjectId  objectId, LONG  uniqueID, ObjectId  parentObjectId = 0, InstanceId  parentInstanceId = 0 )  [inline]

Add an instance of the given object identified by a unique ID The uniqueID cannot be PERF_NO_UNIQUE_ID. Parameters: objectId  The object to add an instance of uniqueId  The unique id of the object parentObjectId  The id of the parent object, if any parentInstanceId  The instance of the parent object, required if a parent object is specified. Throws CPerfDataException on an unexpected validation error (e.g. object not found, parent object/instance not found). Returns 0 if there are no more free instances. You should check for this case.

InstanceId OW32::CPerfData::addInstance (  ObjectId  objectId, LPCWSTR  name, ObjectId  parentObjectId = 0, InstanceId  parentInstanceId = 0 )  [inline]

Add a named instance to the given object. Parameters: objectId  The object to add an instance of name  The name of the object parentObjectId  The id of the parent object, if any parentInstanceId  The instance of the parent object, required if a parent object is specified. Throws CPerfDataException on an unexpected validation error (e.g. object not found, parent object/instance not found). Returns 0 if there are no more free instances. You should check for this case.

void OW32::CPerfData::addObject (  CPerfObject *  object  )

Add a performance object, generally initiated by the PERF_DATA_XXX macros. This should be called before activate. Parameters: object  The object to add

DWORD OW32::CPerfData::collect (  LPWSTR  values, LPVOID *  ppData, LPDWORD  pBytes, LPDWORD  pcObjectTypes )

Collect performance data for the given objects into the given buffer. activate() must be called first. This is generally called from the performance data collection DLL. Parameters: values  Space separated list of object title indexes to collect, or "Global" for all objects. ppData  Pointer to the data buffer. On success, the data buffer pointer is advanced to point just after the data. Unmodified on failure. pBytes  Pointer to the number of bytes written to the data buffer. Will be 0 on failure. pcObjectTypes  Pointer to storage for the number of objects types collected. Will be 0 on failure. ERROR_SUCCESS if successful or ERROR_MORE_DATA if the buffer is insufficiently large. No indication of the required buffer size is given (required by winperf 'specification').

void OW32::CPerfData::deactivate (   )

Disable performance data collection and free allocated resources. Note: this does _not_ free any application defined instances. You should free these yourself. This is not done because you may wish to have than one process creating instances, which is perfectly feasible. The extra book-keeping required to keep track of which process owns which instances is probably not worth it. Clean up after yourself! This is also called by the d'tor of CPerfData (i.e. at application exit), and it is safe to call it more than once, or before calling activate(). Does not throw any exceptions.

BYTE* OW32::CPerfData::getCounter (  ObjectId  objectId, CounterId  counterId, InstanceId  instanceId = 0 )

Get a BYTE* pointer to the storage for the given counter. Parameters: objectId  The object counterId  The counter instanceId  The instance of the object, only for required for multi-instance objects Returns: Pointer to the data storage Throws CPerfDataException on parameter validation error. If the given objectId, counterId and instanceId are all valid this will never throw an exception (these are mainly for debugging). The returned pointer will never be NULL. A pointer, rather than, a reference is returned so that you can avoid the std::map lookups per object per counter.

LONG* OW32::CPerfData::getCounter32 (  ObjectId  objectId, CounterId  counterId, InstanceId  instanceId = 0 )  [inline]

Get a 32-bit pointer to the storage for the given counter. Parameters: objectId  The object counterId  The counter instanceId  The instance of the object, only for required for multi-instance objects Returns: Pointer to the data storage Throws CPerfDataException on parameter validation error. If the given objectId, counterId and instanceId are all valid this will never throw an exception (these are mainly for debugging). The returned pointer will never be NULL. A pointer, rather than, a reference is returned so that you can avoid the std::map lookups per object per counter.

__int64* OW32::CPerfData::getCounter64 (  ObjectId  objectId, CounterId  counterId, InstanceId  instanceId = 0 )  [inline]

Get a 64-bit pointer to the storage for the given counter. Parameters: objectId  The object counterId  The counter instanceId  The instance of the object, only for required for multi-instance objects Returns: Pointer to the data storage Throws CPerfDataException on parameter validation error. If the given objectId, counterId and instanceId are all valid this will never throw an exception (these are mainly for debugging). The returned pointer will never be NULL. A pointer, rather than, a reference is returned so that you can avoid the std::map lookups per object per counter.

CPerfObject* OW32::CPerfData::getObjectById (  ObjectId  objectId  )

Helper function to return a CPerfObject from the it's object id. Parameters: objectId  The object to find Returns: The performance object, or NULL if not found.

void OW32::CPerfData::install (  LPCTSTR  perfCollectorPath  )

Install registry entries for the performance data. Parameters: perfCollectorPath  The path to the collection DLL

bool OW32::CPerfData::lock (  DWORD  timeout = INFINITE  )

Lock object instances so that may be manipulated or read safely. You can also lock counters if you really, really want to -- this will prevent them from being trashed by a different thread, or read in an inconsistent state during collection. However, this is relatively expensive -- it involves a spin lock in the shared region, which in the no wait case is an InterlockedExchange, and in the wait case is sleeping on an event which is then pulsed during unlock. Choose appropriately -- in general, it is not necessary to lock counters as the unlikely possibility of a corrupt value being seen by perfmon is usually only a transient issue. Depends on the counter, of course. The timeout is approximate, unless INFINITE. All internal functions that lock use a timeout of 10s, which prevents a hang. If a hang is detected, a CPerfData exception is thrown.

void OW32::CPerfData::removeInstance (  ObjectId  objectId, InstanceId  instanceId )

Remove the given instance of the given object. Parameters: objectId  The object to remove an instance of instanceId  The instance of the object to remove Throws CPerfDataException on an unexpected validation error (object not found, instance not found).

void OW32::CPerfData::unlock (   )

Unlock object instances. You MUST do this if you call lock(), and there you should wrap any calls after lock in either a SEH frame, or a C++ try/catch(...) construct. If C++, preferably compile with /EHsc (i.e. SEH) to catch all non-C++ exceptions too.

---

The documentation for this class was generated from the following file:

• PerfData.h

---