com.neeve.util

Class UtlThread

java.lang.Object

com.neeve.util.UtlThread

public final class UtlThread
extends Object

Utility class containing methods to worh with threads.

This class IS supported for use by end users..

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	UtlThread.ThreadStats Used by a thread to track stats related to its execution.

Constructor Summary

Constructors

Constructor and Description
UtlThread()

Method Summary

Modifier and Type	Method and Description
static boolean	cpuAffinityMasksEnabled() Returns whether CPU affinitization is enabled or not
static String	decodeAffinityMask(long mask) Returns a mask string for the given mask.
static String	decodeAffinityMask(long mask, boolean physicalFormat) Decodes an affinity mask into a string format.
static void	deregister(Thread thread) Can be called to stop tracking the specified thread.
static void	dumpAffinitizationState(Appendable to, String prefix) Dumps thread affinitization information.
static void	dumpProcessorLayout(Appendable to) Dumps the processor layout to the provided Appendable
static Thread[]	getAllThreads() Gets all running threads in the JVM.
static String	getDefaultCPUAffinityMask() Get the default CPU affinity mask
static UtlThread.ThreadStats	getThreadStats(Thread thread) Gets the thread stats for the given thread.
static void	main(String[] args)
static int	nativeGetThreadStats(long[] threadIds, long[] cpuTimes, long[] userTimes, int[] threadStates, char[][] threadNames, int[] threadNameLengths) Bulk retrieval of per-thread stats from the OS via native code.
static long	parseAffinityMask(String affinity) Parses a mask string into a mask value.
static UtlThread.ThreadStats	registerOrGetThreadStats(Thread thread) Can be called to register a thread for tracking.
static void	setCPUAffinityMask(long mask) Sets the CPU affinity mask of the current thread.
static void	setCPUAffinityMask(String affinity) Sets the CPU affinity mask of the current thread.
static void	setDefaultCPUAffinityMask() Set the CPU affinity mask of the current thread to the default mask
static boolean	threadWaitStatsEnabled() Returns whether thread wait stats are enabled.
static void	triggerThreadDump(Appendable output) Creates a stack dump.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

UtlThread

public UtlThread()

Method Detail

registerOrGetThreadStats

public static final UtlThread.ThreadStats registerOrGetThreadStats(Thread thread)

Can be called to register a thread for tracking.

The caller should call deregister(Thread) when the thread is longer in use.

Parameters:

thread - The thread to register or null if thread stats are not enabled.

deregister

public static void deregister(Thread thread)

Can be called to stop tracking the specified thread.

Parameters:

thread - The thread to deregister.

cpuAffinityMasksEnabled

public static final boolean cpuAffinityMasksEnabled()

Returns whether CPU affinitization is enabled or not

threadWaitStatsEnabled

public static final boolean threadWaitStatsEnabled()

Returns whether thread wait stats are enabled.

setCPUAffinityMask

public static final void setCPUAffinityMask(long mask)

Sets the CPU affinity mask of the current thread.

Parameters:

mask - The affinity mask to set.

Threading:

This method is safe for concurrent access by multiple threads

setCPUAffinityMask

public static void setCPUAffinityMask(String affinity)

Sets the CPU affinity mask of the current thread.

Parameters:

affinity - The affinity mask to set in the form described by parseAffinityMask(String).

See Also:

parseAffinityMask(String)

Threading:

This method is safe for concurrent access by multiple threads

getDefaultCPUAffinityMask

public static String getDefaultCPUAffinityMask()

Get the default CPU affinity mask

Threading:

This method is safe for concurrent access by multiple threads

setDefaultCPUAffinityMask

public static void setDefaultCPUAffinityMask()

Set the CPU affinity mask of the current thread to the default mask

Threading:

This method is safe for concurrent access by multiple threads

parseAffinityMask

public static long parseAffinityMask(String affinity)

Parses a mask string into a mask value. The affinity string can either be a long that represents a mask of logical cpu or a square bracket enclosed comma separated list enumerating the logical cpu

Examples:

• "0" no affinity specified
• "[]" no affinity specified
• "1" specifies logical cpu 0
• "[0]" specifies logical cpu 0
• "4" specifies logical cpu 2
• "[2]" list specifying logical cpu 2
• "6" mask specifying logical cpu 1 and 2
• "4294967296" specifies logical cpu 32
• "[32]" specifies logical cpu 32
• "[1,2]" list specifying logical cpu 1 and 2

Parameters:

affinity - The string describing the affinity mask

Returns:

The affinity mask.

decodeAffinityMask

public static final String decodeAffinityMask(long mask)

Returns a mask string for the given mask.

Parameters:

mask - The mask to decode

Returns:

The mask String in a format that is parsable by parseAffinityMask(String).

decodeAffinityMask

public static final String decodeAffinityMask(long mask,
                                              boolean physicalFormat)

Decodes an affinity mask into a string format.

Parameters:

mask - The mask The mask to decode.

physicalFormat - Attempts to resolve the cores to physical format for the given machine,

Returns:

The mask String.

dumpProcessorLayout

public static final void dumpProcessorLayout(Appendable to)

Dumps the processor layout to the provided Appendable

Parameters:

to - The target to which to dump the processor layout.

dumpAffinitizationState

public static final void dumpAffinitizationState(Appendable to,
                                                 String prefix)

Dumps thread affinitization information.

Parameters:

to - The target to which to dump the affinization state.

getThreadStats

public static final UtlThread.ThreadStats getThreadStats(Thread thread)

Gets the thread stats for the given thread.

Parameters:

thread - The thread for which to retrieve stats.

Returns:

The thread stats (or null if no stats are being tracked for the thread).

See Also:

parseAffinityMask(String)

getAllThreads

public static final Thread[] getAllThreads()

Gets all running threads in the JVM.

This method may be used by end users, but is not supported and is subject to change

Returns:

All running threads, the caller should not modify the returned array.

triggerThreadDump

public static void triggerThreadDump(Appendable output)

Creates a stack dump.

This method may be used by end users, but is not supported and is subject to change

Parameters:

output - the appendable to which to append the dump.

nativeGetThreadStats

public static final int nativeGetThreadStats(long[] threadIds,
                                             long[] cpuTimes,
                                             long[] userTimes,
                                             int[] threadStates,
                                             char[][] threadNames,
                                             int[] threadNameLengths)

Bulk retrieval of per-thread stats from the OS via native code.

All arrays must be pre-allocated by the caller. This method fills them with thread data and returns the number of threads populated. This is a zero-garbage operation: no Java heap allocations are made by the native code.

On platforms where native thread stats are not supported (e.g. Windows), this method returns 0.

Parameters:

threadIds - OUT: OS thread ID per thread

cpuTimes - OUT: total CPU time in nanoseconds per thread

userTimes - OUT: user-mode CPU time in nanoseconds per thread

threadStates - OUT: thread state ordinal per thread (0=RUNNING, 1=SLEEPING, 2=DISK_SLEEP, 3=STOPPED, 4=ZOMBIE, 5=UNKNOWN)

threadNames - OUT: pre-allocated char[] per thread slot, filled with thread name chars

threadNameLengths - OUT: actual length of each thread name

Returns:

the number of threads populated

main

public static final void main(String[] args)