Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Standard Ed. 5.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## java.lang.management
Interface ThreadMXBean

    public interface ThreadMXBean

The management interface for the thread system of the Java virtual machine.

A Java virtual machine has a single instance of the implementation class of this interface. This instance implementing this interface is an MXBean that can be obtained by calling the `ManagementFactory.getThreadMXBean()` method or from the `platform `MBeanServer`` method.

The `ObjectName` for uniquely identifying the MXBean for the thread system within an MBeanServer is:

> ``java.lang:type=Threading``

#### Thread ID

Thread ID is a positive long value returned by calling the `Thread.getId()` method for a thread. The thread ID is unique during its lifetime. When a thread is terminated, this thread ID may be reused.

Some methods in this interface take a thread ID or an array of thread IDs as the input parameter and return per-thread information.

#### Thread CPU time

A Java virtual machine implementation may support measuring the CPU time for the current thread, for any thread, or for no threads.

The `isThreadCpuTimeSupported()` method can be used to determine if a Java virtual machine supports measuring of the CPU time for any thread. The `isCurrentThreadCpuTimeSupported()` method can be used to determine if a Java virtual machine supports measuring of the CPU time for the current thread. A Java virtual machine implementation that supports CPU time measurement for any thread will also support that for the current thread.

The CPU time provided by this interface has nanosecond precision but not necessarily nanosecond accuracy.

A Java virtual machine may disable CPU time measurement by default. The `isThreadCpuTimeEnabled()` and `setThreadCpuTimeEnabled(boolean)` methods can be used to test if CPU time measurement is enabled and to enable/disable this support respectively. Enabling thread CPU measurement could be expensive in some Java virtual machine implementations.

#### Thread Contention Monitoring

Some Java virtual machines may support thread contention monitoring. The `isThreadContentionMonitoringSupported()` method can be used to determine if a Java virtual machine supports thread contention monitoring. The thread contention monitoring is disabled by default. The `setThreadContentionMonitoringEnabled(boolean)` method can be used to enable thread contention monitoring.

Since:
  1.5
See Also:
  JMX Specification., Ways to Access MXBeans

Method Summary
`long[]` | `findMonitorDeadlockedThreads()` Finds cycles of threads that are in deadlock waiting to acquire object monitors.
`long[]` | `getAllThreadIds()` Returns all live thread IDs.
`long` | `getCurrentThreadCpuTime()` Returns the total CPU time for the current thread in nanoseconds.
`long` | `getCurrentThreadUserTime()` Returns the CPU time that the current thread has executed in user mode in nanoseconds.
`int` | `getDaemonThreadCount()` Returns the current number of live daemon threads.
`int` | `getPeakThreadCount()` Returns the peak live thread count since the Java virtual machine started or peak was reset.
`int` | `getThreadCount()` Returns the current number of live threads including both daemon and non-daemon threads.
`long` | `getThreadCpuTime(long id)` Returns the total CPU time for a thread of the specified ID in nanoseconds.
`ThreadInfo` | `getThreadInfo(long id)` Returns the thread info for a thread of the specified `id` with no stack trace.
`ThreadInfo[]` | `getThreadInfo(long[] ids)` Returns the thread info for each thread whose ID is in the input array `ids` with no stack trace.
`ThreadInfo[]` | `getThreadInfo(long[] ids, int maxDepth)` Returns the thread info for each thread whose ID is in the input array `ids`.
`ThreadInfo` | `getThreadInfo(long id, int maxDepth)` Returns a thread info for a thread of the specified `id`.
`long` | `getThreadUserTime(long id)` Returns the CPU time that a thread of the specified ID has executed in user mode in nanoseconds.
`long` | `getTotalStartedThreadCount()` Returns the total number of threads created and also started since the Java virtual machine started.
`boolean` | `isCurrentThreadCpuTimeSupported()` Tests if the Java virtual machine supports CPU time measurement for the current thread.
`boolean` | `isThreadContentionMonitoringEnabled()` Tests if thread contention monitoring is enabled.
`boolean` | `isThreadContentionMonitoringSupported()` Tests if the Java virtual machine supports thread contention monitoring.
`boolean` | `isThreadCpuTimeEnabled()` Tests if thread CPU time measurement is enabled.
`boolean` | `isThreadCpuTimeSupported()` Tests if the Java virtual machine implementation supports CPU time measurement for any thread.
`void` | `resetPeakThreadCount()` Resets the peak thread count to the current number of live threads.
`void` | `setThreadContentionMonitoringEnabled(boolean enable)` Enables or disables thread contention monitoring.
`void` | `setThreadCpuTimeEnabled(boolean enable)` Enables or disables thread CPU time measurement.

Method Detail

### getThreadCount

    int getThreadCount()

  Returns the current number of live threads including both daemon and non-daemon threads.

  Returns:
    the current number of live threads.

### getPeakThreadCount

    int getPeakThreadCount()

  Returns the peak live thread count since the Java virtual machine started or peak was reset.

  Returns:
    the peak live thread count.

### getTotalStartedThreadCount

    long getTotalStartedThreadCount()

  Returns the total number of threads created and also started since the Java virtual machine started.

  Returns:
    the total number of threads started.

### getDaemonThreadCount

    int getDaemonThreadCount()

  Returns the current number of live daemon threads.

  Returns:
    the current number of live daemon threads.

### getAllThreadIds

    long[] getAllThreadIds()

  Returns all live thread IDs. Some threads included in the returned array may have been terminated when this method returns.

  Returns:
    an array of `long`, each is a thread ID.
  Throws:
    `SecurityException` - if a security manager exists and the caller does not have ManagementPermission("monitor").

### getThreadInfo

    ThreadInfo getThreadInfo(long id)

  Returns the thread info for a thread of the specified `id` with no stack trace. This method is equivalent to calling:

  > `getThreadInfo(id, 0);`

  This method returns a `ThreadInfo` object representing the thread information for the thread of the specified ID. The stack trace in the returned `ThreadInfo` object will be an empty array of `StackTraceElement`. If a thread of the given ID is not alive or does not exist, this method will return `null`. A thread is alive if it has been started and has not yet died.

  MBeanServer access:
  The mapped type of `ThreadInfo` is `CompositeData` with attributes as specified in `ThreadInfo`.

  Parameters:
    `id` - the thread ID of the thread. Must be positive.
  Returns:
    a `ThreadInfo` object for the thread of the given ID with no stack trace; `null` if the thread of the given ID is not alive or it does not exist.
  Throws:
    `IllegalArgumentException` - if `id <= 0`.
    `SecurityException` - if a security manager exists and the caller does not have ManagementPermission("monitor").

### getThreadInfo

    ThreadInfo[] getThreadInfo(long[] ids)

  Returns the thread info for each thread whose ID is in the input array `ids` with no stack trace. This method is equivalent to calling:

  >        getThreadInfo(ids, 0);

  This method returns an array of the `ThreadInfo` objects. The stack trace in each `ThreadInfo` object will be an empty array of `StackTraceElement`. If a thread of a given ID is not alive or does not exist, the corresponding element in the returned array will contain `null`. A thread is alive if it has been started and has not yet died.

  MBeanServer access:
  The mapped type of `ThreadInfo` is `CompositeData` with attributes as specified in `ThreadInfo`.

  Parameters:
    `ids` - an array of thread IDs
  Returns:
    an array of the `ThreadInfo` objects, each containing information about a thread whose ID is in the corresponding element of the input array of IDs.
  Throws:
    `IllegalArgumentException` - if any element in the input array `ids` is `<= 0`.
    `SecurityException` - if a security manager exists and the caller does not have ManagementPermission("monitor").

### getThreadInfo

    ThreadInfo getThreadInfo(long id,
                             int maxDepth)

  Returns a thread info for a thread of the specified `id`. The `maxDepth` parameter indicates the maximum number of `StackTraceElement` to be retrieved from the stack trace. If `maxDepth == Integer.MAX_VALUE`, the entire stack trace of the thread will be dumped. If `maxDepth == 0`, no stack trace of the thread will be dumped.

  When the Java virtual machine has no stack trace information about a thread or `maxDepth == 0`, the stack trace in the `ThreadInfo` object will be an empty array of `StackTraceElement`.

  If a thread of the given ID is not alive or does not exist, this method will return `null`. A thread is alive if it has been started and has not yet died.

  MBeanServer access:
  The mapped type of `ThreadInfo` is `CompositeData` with attributes as specified in `ThreadInfo`.

  Parameters:
    `id` - the thread ID of the thread. Must be positive.
    `maxDepth` - the maximum number of entries in the stack trace to be dumped. `Integer.MAX_VALUE` could be used to request the entire stack to be dumped.
  Returns:
    a `ThreadInfo` of the thread of the given ID. `null` if the thread of the given ID is not alive or it does not exist.
  Throws:
    `IllegalArgumentException` - if `id <= 0`.
    `IllegalArgumentException` - if `maxDepth is negative`.
    `SecurityException` - if a security manager exists and the caller does not have ManagementPermission("monitor").

### getThreadInfo

    ThreadInfo[] getThreadInfo(long[] ids,
                               int maxDepth)

  Returns the thread info for each thread whose ID is in the input array `ids`. The `maxDepth` parameter indicates the maximum number of `StackTraceElement` to be retrieved from the stack trace. If `maxDepth == Integer.MAX_VALUE`, the entire stack trace of the thread will be dumped. If `maxDepth == 0`, no stack trace of the thread will be dumped.

  When the Java virtual machine has no stack trace information about a thread or `maxDepth == 0`, the stack trace in the `ThreadInfo` object will be an empty array of `StackTraceElement`.

  This method returns an array of the `ThreadInfo` objects, each is the thread information about the thread with the same index as in the `ids` array. If a thread of the given ID is not alive or does not exist, `null` will be set in the corresponding element in the returned array. A thread is alive if it has been started and has not yet died.

  MBeanServer access:
  The mapped type of `ThreadInfo` is `CompositeData` with attributes as specified in `ThreadInfo`.

  Parameters:
    `ids` - an array of thread IDs
    `maxDepth` - the maximum number of entries in the stack trace to be dumped. `Integer.MAX_VALUE` could be used to request the entire stack to be dumped.
  Returns:
    an array of the `ThreadInfo` objects, each containing information about a thread whose ID is in the corresponding element of the input array of IDs.
  Throws:
    `IllegalArgumentException` - if `maxDepth is negative`.
    `IllegalArgumentException` - if any element in the input array `ids` is `<= 0`.
    `SecurityException` - if a security manager exists and the caller does not have ManagementPermission("monitor").

### isThreadContentionMonitoringSupported

    boolean isThreadContentionMonitoringSupported()

  Tests if the Java virtual machine supports thread contention monitoring.

  Returns:
    `true` if the Java virtual machine supports thread contention monitoring; `false` otherwise.

### isThreadContentionMonitoringEnabled

    boolean isThreadContentionMonitoringEnabled()

  Tests if thread contention monitoring is enabled.

  Returns:
    `true` if thread contention monitoring is enabled; `false` otherwise.
  Throws:
    `UnsupportedOperationException` - if the Java virtual machine does not support thread contention monitoring.
  See Also:
    `isThreadContentionMonitoringSupported()`

### setThreadContentionMonitoringEnabled

    void setThreadContentionMonitoringEnabled(boolean enable)

  Enables or disables thread contention monitoring. Thread contention monitoring is disabled by default.

  Parameters:
    `enable` - `true` to enable; `false` to disable.
  Throws:
    `UnsupportedOperationException` - if the Java virtual machine does not support thread contention monitoring.
    `SecurityException` - if a security manager exists and the caller does not have ManagementPermission("control").
  See Also:
    `isThreadContentionMonitoringSupported()`

### getCurrentThreadCpuTime

    long getCurrentThreadCpuTime()

  Returns the total CPU time for the current thread in nanoseconds. The returned value is of nanoseconds precison but not necessarily nanoseconds accuracy. If the implementation distinguishes between user mode time and system mode time, the returned CPU time is the amount of time that the current thread has executed in user mode or system mode.

  This is a convenient method for local management use and is equivalent to calling:

  >        getThreadCpuTime(Thread.currentThread().getId());

  Returns:
    the total CPU time for the current thread if CPU time measurement is enabled; `-1` otherwise.
  Throws:
    `UnsupportedOperationException` - if the Java virtual machine does not support CPU time measurement for the current thread.
  See Also:
    `getCurrentThreadUserTime()`, `isCurrentThreadCpuTimeSupported()`, `isThreadCpuTimeEnabled()`, `setThreadCpuTimeEnabled(boolean)`

### getCurrentThreadUserTime

    long getCurrentThreadUserTime()

  Returns the CPU time that the current thread has executed in user mode in nanoseconds. The returned value is of nanoseconds precison but not necessarily nanoseconds accuracy.

  This is a convenient method for local management use and is equivalent to calling:

  >        getThreadUserTime(Thread.currentThread().getId());

  Returns:
    the user-level CPU time for the current thread if CPU time measurement is enabled; `-1` otherwise.
  Throws:
    `UnsupportedOperationException` - if the Java virtual machine does not support CPU time measurement for the current thread.
  See Also:
    `getCurrentThreadCpuTime()`, `isCurrentThreadCpuTimeSupported()`, `isThreadCpuTimeEnabled()`, `setThreadCpuTimeEnabled(boolean)`

### getThreadCpuTime

    long getThreadCpuTime(long id)

  Returns the total CPU time for a thread of the specified ID in nanoseconds. The returned value is of nanoseconds precision but not necessarily nanoseconds accuracy. If the implementation distinguishes between user mode time and system mode time, the returned CPU time is the amount of time that the thread has executed in user mode or system mode.

  If the thread of the specified ID is not alive or does not exist, this method returns `-1`. If CPU time measurement is disabled, this method returns `-1`. A thread is alive if it has been started and has not yet died.

  If CPU time measurement is enabled after the thread has started, the Java virtual machine implementation may choose any time up to and including the time that the capability is enabled as the point where CPU time measurement starts.

  Parameters:
    `id` - the thread ID of a thread
  Returns:
    the total CPU time for a thread of the specified ID if the thread of the specified ID exists, the thread is alive, and CPU time measurement is enabled; `-1` otherwise.
  Throws:
    `IllegalArgumentException` - if `id <= 0` .
    `UnsupportedOperationException` - if the Java virtual machine does not support CPU time measurement for other threads.
  See Also:
    `getThreadUserTime(long)`, `isThreadCpuTimeSupported()`, `isThreadCpuTimeEnabled()`, `setThreadCpuTimeEnabled(boolean)`

### getThreadUserTime

    long getThreadUserTime(long id)

  Returns the CPU time that a thread of the specified ID has executed in user mode in nanoseconds. The returned value is of nanoseconds precision but not necessarily nanoseconds accuracy.

  If the thread of the specified ID is not alive or does not exist, this method returns `-1`. If CPU time measurement is disabled, this method returns `-1`. A thread is alive if it has been started and has not yet died.

  If CPU time measurement is enabled after the thread has started, the Java virtual machine implementation may choose any time up to and including the time that the capability is enabled as the point where CPU time measurement starts.

  Parameters:
    `id` - the thread ID of a thread
  Returns:
    the user-level CPU time for a thread of the specified ID if the thread of the specified ID exists, the thread is alive, and CPU time measurement is enabled; `-1` otherwise.
  Throws:
    `IllegalArgumentException` - if `id <= 0` .
    `UnsupportedOperationException` - if the Java virtual machine does not support CPU time measurement for other threads.
  See Also:
    `getThreadCpuTime(long)`, `isThreadCpuTimeSupported()`, `isThreadCpuTimeEnabled()`, `setThreadCpuTimeEnabled(boolean)`

### isThreadCpuTimeSupported

    boolean isThreadCpuTimeSupported()

  Tests if the Java virtual machine implementation supports CPU time measurement for any thread. A Java virtual machine implementation that supports CPU time measurement for any thread will also support CPU time measurement for the current thread.

  Returns:
    `true` if the Java virtual machine supports CPU time measurement for any thread; `false` otherwise.

### isCurrentThreadCpuTimeSupported

    boolean isCurrentThreadCpuTimeSupported()

  Tests if the Java virtual machine supports CPU time measurement for the current thread. This method returns `true` if `isThreadCpuTimeSupported()` returns `true`.

  Returns:
    `true` if the Java virtual machine supports CPU time measurement for current thread; `false` otherwise.

### isThreadCpuTimeEnabled

    boolean isThreadCpuTimeEnabled()

  Tests if thread CPU time measurement is enabled.

  Returns:
    `true` if thread CPU time measurement is enabled; `false` otherwise.
  Throws:
    `UnsupportedOperationException` - if the Java virtual machine does not support CPU time measurement for other threads nor for the current thread.
  See Also:
    `isThreadCpuTimeSupported()`, `isCurrentThreadCpuTimeSupported()`

### setThreadCpuTimeEnabled

    void setThreadCpuTimeEnabled(boolean enable)

  Enables or disables thread CPU time measurement. The default is platform dependent.

  Parameters:
    `enable` - `true` to enable; `false` to disable.
  Throws:
    `UnsupportedOperationException` - if the Java virtual machine does not support CPU time measurement for any threads nor for the current thread.
    `SecurityException` - if a security manager exists and the caller does not have ManagementPermission("control").
  See Also:
    `isThreadCpuTimeSupported()`, `isCurrentThreadCpuTimeSupported()`

### findMonitorDeadlockedThreads

    long[] findMonitorDeadlockedThreads()

  Finds cycles of threads that are in deadlock waiting to acquire object monitors. That is, threads that are blocked waiting to enter a synchronization block or waiting to reenter a synchronization block after an `Object.wait` call, where each thread owns one monitor while trying to obtain another monitor already held by another thread in a cycle.

  More formally, a thread is monitor deadlocked if it is part of a cycle in the relation "is waiting for an object monitor owned by". In the simplest case, thread A is blocked waiting for a monitor owned by thread B, and thread B is blocked waiting for a monitor owned by thread A.

  This method is designed for troubleshooting use, but not for synchronization control. It might be an expensive operation.

  Returns:
    an array of IDs of the threads that are monitor deadlocked, if any; `null` otherwise.
  Throws:
    `SecurityException` - if a security manager exists and the caller does not have ManagementPermission("monitor").

### resetPeakThreadCount

    void resetPeakThreadCount()

  Resets the peak thread count to the current number of live threads.

  Throws:
    `SecurityException` - if a security manager exists and the caller does not have ManagementPermission("control").
  See Also:
    `getPeakThreadCount()`, `getThreadCount()`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Standard Ed. 5.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Copyright 2004 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.