com.sun.rtsjx
Interface ImportantThreadsMXBean

public interface ImportantThreadsMXBean

Monitoring and changing the behavior of non-critical real-time threads for the Real-Time Garbage Collector.

This class is still under development and may evolve for the future versions of the product.

For a complete description of the RTGC, look at the Java RTS Garbage Collection Guide. This is a short summary relevant for this particular MBean.

Important threads are the non-critical real-time threads running above the default priority of the RTGC. Tuning mechanisms try to start the RTGC soon enough to complete at that priority. To ensure the determinism of the critical threads, the RTGC may have to be boosted if it did not complete on time. In that case, the important threads might be preempted as long as the RTGC runs. On a multi-processor machine, they can continue running on other processors. However, if memory goes below a minimum threshold reserved for critical threads, important threads block.

This interface allows you to change the parameters and to monitor the throughput and the determinism. getLongestTimeBoosted() returns the longest preemption time. If the RTGC can use all the processors, this defines the pause time for the important threads. When there are spare processors, getLongestTimeWithAllocationBlocked() returns the longest time during which the allocations were blocked. This defines the pause time on those machines.

The 'boosted' sliding value and the parameters that impact it can be ignored on uniprocessors. Users can focus on the 'normal' attributes in that case.

Note that parameter changes might be delayed up to the next GC cycle.

Method Summary

void	changeBoostedPriority(int priority) Change the maximum priority of the RTGC.
void	changeNormalPriority(int priority) Change the default priority of the RTGC.
void	changeNormalWorkers(int workers) Change the default number of active RTGC worker threads.
void	changeSlidingBoostedModeAllocations(long value) Change the evolving threshold boosting the RTGC over important threads.
void	changeSlidingNormalModeAllocations(long value) Change the evolving threshold which defines when the RTGC starts.
long	getAllocatedBytes() Total bytes allocated at priority higher than default priority.
long	getBoostedMinFreeBytes() Minimum boosted memory threshold.
int	getBoostedPriority() Maximum priority of the RTGC.
long	getBoostedSafetyMargin() Margin to avoid bursty boosted allocations.
long	getBoostedSlideFactor() Percentage lowering old worst case boosted allocation.
int	getBoostedWorkers() Maximum number of active RTGC worker threads.
java.lang.String	getDescription() Short description of the MBean.
long	getLongestTimeBoosted() Worst time spent with the RTGC running at boosted priority.
long	getLongestTimeWithAllocationBlocked() Worst time spent with the memory reserved for critical threads.
long	getNormalMinFreeBytes() Minimum normal memory threshold.
int	getNormalPriority() Default priority of the RTGC.
long	getNormalSafetyMargin() Margin to avoid bursty allocations.
long	getNormalSlideFactor() Percentage lowering old worst case allocation.
int	getNormalWorkers() Default number of active RTGC worker threads.
long	getRecentAllocationRate() Bytes per milliseconds allocated by important and critical threads since the last call to reset().
long	getSlidingBoostedModeAllocations() Evolving threshold boosting the RTGC over important threads.
long	getSlidingNormalModeAllocations() Evolving threshold which defines when the RTGC starts.
long	getTotalTimeBoosted() Total time spent with the RTGC running at boosted priority.
long	getTotalTimeWithAllocationBlocked() Total time spent with the memory reserved for critical threads.
void	reset() Resets the worst case numbers and long term usage computation.
void	setBoostedMinFreeBytes(long value) Change the minimum boosted memory threshold.
void	setBoostedSafetyMargin(long value) Change the margin to avoid bursty boosted allocations.
void	setBoostedSlideFactor(long value) Change the percentage lowering old worst case boosted allocation.
void	setNormalMinFreeBytes(long value) Change the minimum normal memory threshold.
void	setNormalSafetyMargin(long value) Change the margin to avoid bursty allocations.
void	setNormalSlideFactor(long value) Change the percentage lowering old worst case allocation.

Method Detail

getDescription

java.lang.String getDescription()

Short description of the MBean.

Returns:

a string describing this MBean.

getNormalPriority

int getNormalPriority()

Default priority of the RTGC.

Returns:

the RTGC default priority.

changeNormalPriority

void changeNormalPriority(int priority)

Change the default priority of the RTGC.

By increasing this value, the number of important threads decreases. This improves the chances that these threads will not be preempted and will not block on allocation.

The change is asynchronous and might be delayed. In addition, the RTGC might apply a slightly different value to ensure the consistency of the parameters.

Parameters:

priority - new default priority.

getNormalWorkers

int getNormalWorkers()

Default number of active RTGC worker threads.

Returns:

the default number of active RTGC threads.

changeNormalWorkers

void changeNormalWorkers(int workers)

Change the default number of active RTGC worker threads.

By decreasing this value, threads running at a priority lower than NormalPriority will get more CPU cycles when the RTGC need not be boosted. The trade-off is that the RTGC may have to be boosted more often, thus impacting the important threads.

The change is asynchronous and might be delayed. In addition, the RTGC might apply a slightly different value to ensure the consistency of the parameters.

Parameters:

workers - new default number of active RTGC worker threads.

getBoostedWorkers

int getBoostedWorkers()

Maximum number of active RTGC worker threads.

Returns:

the maximum number of active RTGC threads.

getBoostedPriority

int getBoostedPriority()

Maximum priority of the RTGC.

Returns:

the RTGC maximum priority.

changeBoostedPriority

void changeBoostedPriority(int priority)

Change the maximum priority of the RTGC.

The change is asynchronous and might be delayed. In addition, the RTGC might apply a slightly different value to ensure the consistency of the parameters.

Parameters:

priority - new maximum priority.

getSlidingBoostedModeAllocations

long getSlidingBoostedModeAllocations()

Evolving threshold boosting the RTGC over important threads.

The lower the value, the later the RTGC is boosted. This improves throughput but may impact determinism on a multi-processor machine. Boosting the RTGC earlier may allow it to complete while the important threads with the highest priority can still allocate memory on spare processors.

Returns:

the current memory threshold.

changeSlidingBoostedModeAllocations

void changeSlidingBoostedModeAllocations(long value)

Change the evolving threshold boosting the RTGC over important threads.

The user can increase it to speed up the auto-tuning or start with a safer margin and avoid the initial pauses. This temporarily impacts throughput.

Parameters:

value - threshold for the next run.

getBoostedMinFreeBytes

long getBoostedMinFreeBytes()

Minimum boosted memory threshold.

Auto-tuning will not go below this limit. The RTGC will always be boosted when the memory reaches this threshold.

Returns:

Minimum boosted memory threshold.

setBoostedMinFreeBytes

void setBoostedMinFreeBytes(long value)

Change the minimum boosted memory threshold.

A higher value prevents the auto-tuning from reaching very high performance by lowering the threshold when the allocation rate drops. However, it improves determinism when the allocation rate starts going up.

Parameters:

value - minimum boosted memory threshold.

getBoostedSlideFactor

long getBoostedSlideFactor()

Percentage lowering old worst case boosted allocation.

The RTGC Guide describes how it impacts the dynamic threshold.

Returns:

Percentage lowering old worst case boosted allocation.

setBoostedSlideFactor

void setBoostedSlideFactor(long value)

Change the percentage lowering old worst case boosted allocation.

The RTGC Guide describes how it impacts the dynamic threshold.

Parameters:

value - percentage lowering old worst case boosted allocation.

getBoostedSafetyMargin

long getBoostedSafetyMargin()

Margin to avoid bursty boosted allocations.

The RTGC Guide describes how it impacts the dynamic threshold.

Returns:

Margin to avoid bursty boosted allocations.

setBoostedSafetyMargin

void setBoostedSafetyMargin(long value)

Change the margin to avoid bursty boosted allocations.

The RTGC Guide describes how it impacts the dynamic threshold.

Parameters:

value - margin to avoid bursty boosted allocations.

getSlidingNormalModeAllocations

long getSlidingNormalModeAllocations()

Evolving threshold which defines when the RTGC starts.

The lower the value, the later the RTGC starts. This improves the throughput but may impact determinism. The RTGC may have to be boosted to its maximum priority if it starts too late. It may even have to block the non-critical threads. The user can increase it to speed up the auto-tuning or start with a safer margin and avoid the initial pauses.

Returns:

the current memory threshold.

changeSlidingNormalModeAllocations

void changeSlidingNormalModeAllocations(long value)

Change the evolving threshold which defines when the RTGC starts.

The user can increase it to speed up the auto-tuning or start with a safer margin and avoid the initial pauses. This temporarily impacts throughput.

Parameters:

value - threshold for the next run.

getNormalMinFreeBytes

long getNormalMinFreeBytes()

Minimum normal memory threshold.

Auto-tuning will not go below this limit. The RTGC will always start when the memory reaches this threshold.

Returns:

Minimum normal memory threshold.

setNormalMinFreeBytes

void setNormalMinFreeBytes(long value)

Change the minimum normal memory threshold.

A higher value prevents the auto-tuning from reaching very high performance by lowering the threshold when the allocation rate drops. However, it improves determinism when the allocation rate starts going up.

Parameters:

value - minimum normal memory threshold.

getNormalSlideFactor

long getNormalSlideFactor()

Percentage lowering old worst case allocation.

The RTGC Guide describes how it impacts the dynamic threshold.

Returns:

Percentage lowering old worst case allocation.

setNormalSlideFactor

void setNormalSlideFactor(long value)

Change the percentage lowering old worst case allocation.

The RTGC Guide describes how it impacts the dynamic threshold.

Parameters:

value - percentage lowering old worst case allocation.

getNormalSafetyMargin

long getNormalSafetyMargin()

Margin to avoid bursty allocations.

The RTGC Guide describes how it impacts the dynamic threshold.

Returns:

Margin to avoid bursty allocations.

setNormalSafetyMargin

void setNormalSafetyMargin(long value)

Change the margin to avoid bursty allocations.

The RTGC Guide describes how it impacts the dynamic threshold.

Parameters:

value - margin to avoid bursty allocations.

getAllocatedBytes

long getAllocatedBytes()

Total bytes allocated at priority higher than default priority.

This includes the bytes allocated by critical threads.

Returns:

Total bytes allocated at priority higher than default priority.

getRecentAllocationRate

long getRecentAllocationRate()

Bytes per milliseconds allocated by important and critical threads since the last call to reset().

Returns:

bytes per milliseconds

getTotalTimeBoosted

long getTotalTimeBoosted()

Total time spent with the RTGC running at boosted priority.

This defines the total pause time for important threads.

Returns:

Total time spent with the RTGC running at boosted priority.

getLongestTimeBoosted

long getLongestTimeBoosted()

Worst time spent with the RTGC running at boosted priority.

This defines the worst pause time for important threads when there is no spare processors.

Returns:

Worst time spent with the RTGC running at boosted priority.

getLongestTimeWithAllocationBlocked

long getLongestTimeWithAllocationBlocked()

Worst time spent with the memory reserved for critical threads.

This defines the worst pause time for important threads when the RTGC does not use all the processors.

Returns:

Worst time spent with the memory reserved for critical threads

getTotalTimeWithAllocationBlocked

long getTotalTimeWithAllocationBlocked()

Total time spent with the memory reserved for critical threads.

This defines the total pause time for important threads when the RTGC does not use all the processors.

Returns:

Total time spent with the memory reserved for critical threads.

reset

void reset()

Resets the worst case numbers and long term usage computation. This impacts the allocation rate and the attribute reporting longest times.