System::getLockContentionStats Method

Product Information > JADE Object Manager Guide > Chapter 4 - JADE System Instrumentation and Diagnosis > SystemgetLockContentionStats Method

System::getLockContentionStats Method

The System class getLockContentionStats method retrieves lock contention information. A lock contention occurs when an attempt to lock a persistent object is queued or rejected because the object is already locked. The information includes the number of lock contentions for individual objects and the average and maximum times spent waiting to acquire a lock on each individual object. Information is returned in transient instances of the LockContentionInfo class, added to the transient ObjectArray instance specified by the oa parameter.

The value of the maxEntries parameter specifies the maximum number of entries to be returned. Returned entries are added to the array in no particular order. When the maxEntries limit is reached, no more entries are added.

The value of the minContentions parameter specifies the minimum number of contentions for entries to be returned. Only entries with contention counts greater than or equal to the specified minimum are returned.

The startTime parameter is an output parameter that is set to the time at which the lock contention recording was started or restarted. This value enables you to calculate the number of contentions per second.

The calling method is responsible for creating and deleting the transient ObjectArray instance and for deleting LockContentionInfo instances in the array (for example, by using the purge method on the ObjectArray instance before deleting it). When the method is called, any existing LockContentionInfo instances in the array are not removed. New LockContentionInfo instances are added to the end of the array.

If lock contentions are not being recorded when the getLockContentionStats method is called, no entries are added to the ObjectArray instance. You can use the queryLockContentionStats method to determine if lock contentions are currently being recorded.

The information available in LockContentionInfo instances is listed in the following table.

Feature	Description
target	Returns a reference to the object being locked
totalContentions	Contains the number of lock contentions recorded for the object
maxWaitTime	Contains the longest time in milliseconds that any process spent queued waiting to obtain a lock on the object
totalWaitTime	Contains the total time in milliseconds that all processes spent queued waiting to obtain locks on the object

A LockContentionInfo instance with a null object reference for the target value indicates that it holds combined information for all contentions that occurred on objects that could not be included in the table because the maximum table size had been reached.