1 /*

     2  * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 package com.sun.management;

    27 

    28 import java.util.Map;

    29 

    30 /**

    31  * Platform-specific management interface for the thread system

    32  * of the Java virtual machine.

    33  * <p>

    34  * This platform extension is only available to a thread

    35  * implementation that supports this extension.

    36  *

    37  * @author  Paul Hohensee

    38  * @since   6u25

    39  */

    40 

    41 @jdk.Exported

    42 public interface ThreadMXBean extends java.lang.management.ThreadMXBean {

    43     /**

    44      * Returns the total CPU time for each thread whose ID is

    45      * in the input array {@code ids} in nanoseconds.

    46      * The returned values are of nanoseconds precision but

    47      * not necessarily nanoseconds accuracy.

    48      * <p>

    49      * This method is equivalent to calling the

    50      * {@link ThreadMXBean#getThreadCpuTime(long)}

    51      * method for each thread ID in the input array {@code ids} and setting the

    52      * returned value in the corresponding element of the returned array.

    53      *

    54      * @param ids an array of thread IDs.

    55      * @return an array of long values, each of which is the amount of CPU

    56      * time the thread whose ID is in the corresponding element of the input

    57      * array of IDs has used,

    58      * if the thread of a specified ID exists, the thread is alive,

    59      * and CPU time measurement is enabled;

    60      * {@code -1} otherwise.

    61      *

    62      * @throws NullPointerException if {@code ids} is {@code null}

    63      * @throws IllegalArgumentException if any element in the input array

    64      *         {@code ids} is {@code <=} {@code 0}.

    65      * @throws java.lang.UnsupportedOperationException if the Java

    66      *         virtual machine implementation does not support CPU time

    67      *         measurement.

    68      *

    69      * @see ThreadMXBean#getThreadCpuTime(long)

    70      * @see #getThreadUserTime

    71      * @see ThreadMXBean#isThreadCpuTimeSupported

    72      * @see ThreadMXBean#isThreadCpuTimeEnabled

    73      * @see ThreadMXBean#setThreadCpuTimeEnabled

    74      */

    75     public long[] getThreadCpuTime(long[] ids);

    76 

    77     /**

    78      * Returns the CPU time that each thread whose ID is in the input array

    79      * {@code ids} has executed in user mode in nanoseconds.

    80      * The returned values are of nanoseconds precision but

    81      * not necessarily nanoseconds accuracy.

    82      * <p>

    83      * This method is equivalent to calling the

    84      * {@link ThreadMXBean#getThreadUserTime(long)}

    85      * method for each thread ID in the input array {@code ids} and setting the

    86      * returned value in the corresponding element of the returned array.

    87      *

    88      * @param ids an array of thread IDs.

    89      * @return an array of long values, each of which is the amount of user

    90      * mode CPU time the thread whose ID is in the corresponding element of

    91      * the input array of IDs has used,

    92      * if the thread of a specified ID exists, the thread is alive,

    93      * and CPU time measurement is enabled;

    94      * {@code -1} otherwise.

    95      *

    96      * @throws NullPointerException if {@code ids} is {@code null}

    97      * @throws IllegalArgumentException if any element in the input array

    98      *         {@code ids} is {@code <=} {@code 0}.

    99      * @throws java.lang.UnsupportedOperationException if the Java

   100      *         virtual machine implementation does not support CPU time

   101      *         measurement.

   102      *

   103      * @see ThreadMXBean#getThreadUserTime(long)

   104      * @see #getThreadCpuTime

   105      * @see ThreadMXBean#isThreadCpuTimeSupported

   106      * @see ThreadMXBean#isThreadCpuTimeEnabled

   107      * @see ThreadMXBean#setThreadCpuTimeEnabled

   108      */

   109     public long[] getThreadUserTime(long[] ids);

   110 

   111     /**

   112      * Returns an approximation of the total amount of memory, in bytes,

   113      * allocated in heap memory for the thread of the specified ID.

   114      * The returned value is an approximation because some Java virtual machine

   115      * implementations may use object allocation mechanisms that result in a

   116      * delay between the time an object is allocated and the time its size is

   117      * recorded.

   118      * <p>

   119      * If the thread of the specified ID is not alive or does not exist,

   120      * this method returns {@code -1}. If thread memory allocation measurement

   121      * is disabled, this method returns {@code -1}.

   122      * A thread is alive if it has been started and has not yet died.

   123      * <p>

   124      * If thread memory allocation measurement is enabled after the thread has

   125      * started, the Java virtual machine implementation may choose any time up

   126      * to and including the time that the capability is enabled as the point

   127      * where thread memory allocation measurement starts.

   128      *

   129      * @param id the thread ID of a thread

   130      * @return an approximation of the total memory allocated, in bytes, in

   131      * heap memory for a thread of the specified ID

   132      * if the thread of the specified ID exists, the thread is alive,

   133      * and thread memory allocation measurement is enabled;

   134      * {@code -1} otherwise.

   135      *

   136      * @throws IllegalArgumentException if {@code id} {@code <=} {@code 0}.

   137      * @throws java.lang.UnsupportedOperationException if the Java virtual

   138      *         machine implementation does not support thread memory allocation

   139      *         measurement.

   140      *

   141      * @see #isThreadAllocatedMemorySupported

   142      * @see #isThreadAllocatedMemoryEnabled

   143      * @see #setThreadAllocatedMemoryEnabled

   144      */

   145     public long getThreadAllocatedBytes(long id);

   146 

   147     /**

   148      * Returns an approximation of the total amount of memory, in bytes,

   149      * allocated in heap memory for each thread whose ID is in the input

   150      * array {@code ids}.

   151      * The returned values are approximations because some Java virtual machine

   152      * implementations may use object allocation mechanisms that result in a

   153      * delay between the time an object is allocated and the time its size is

   154      * recorded.

   155      * <p>

   156      * This method is equivalent to calling the

   157      * {@link #getThreadAllocatedBytes(long)}

   158      * method for each thread ID in the input array {@code ids} and setting the

   159      * returned value in the corresponding element of the returned array.

   160      *

   161      * @param ids an array of thread IDs.

   162      * @return an array of long values, each of which is an approximation of

   163      * the total memory allocated, in bytes, in heap memory for the thread

   164      * whose ID is in the corresponding element of the input array of IDs.

   165      *

   166      * @throws NullPointerException if {@code ids} is {@code null}

   167      * @throws IllegalArgumentException if any element in the input array

   168      *         {@code ids} is {@code <=} {@code 0}.

   169      * @throws java.lang.UnsupportedOperationException if the Java virtual

   170      *         machine implementation does not support thread memory allocation

   171      *         measurement.

   172      *

   173      * @see #getThreadAllocatedBytes(long)

   174      * @see #isThreadAllocatedMemorySupported

   175      * @see #isThreadAllocatedMemoryEnabled

   176      * @see #setThreadAllocatedMemoryEnabled

   177      */

   178     public long[] getThreadAllocatedBytes(long[] ids);

   179 

   180     /**

   181      * Tests if the Java virtual machine implementation supports thread memory

   182      * allocation measurement.

   183      *

   184      * @return

   185      *   {@code true}

   186      *     if the Java virtual machine implementation supports thread memory

   187      *     allocation measurement;

   188      *   {@code false} otherwise.

   189      */

   190     public boolean isThreadAllocatedMemorySupported();

   191 

   192     /**

   193      * Tests if thread memory allocation measurement is enabled.

   194      *

   195      * @return {@code true} if thread memory allocation measurement is enabled;

   196      *         {@code false} otherwise.

   197      *

   198      * @throws java.lang.UnsupportedOperationException if the Java virtual

   199      *         machine does not support thread memory allocation measurement.

   200      *

   201      * @see #isThreadAllocatedMemorySupported

   202      */

   203     public boolean isThreadAllocatedMemoryEnabled();

   204 

   205     /**

   206      * Enables or disables thread memory allocation measurement.  The default

   207      * is platform dependent.

   208      *

   209      * @param enable {@code true} to enable;

   210      *               {@code false} to disable.

   211      *

   212      * @throws java.lang.UnsupportedOperationException if the Java virtual

   213      *         machine does not support thread memory allocation measurement.

   214      *

   215      * @throws java.lang.SecurityException if a security manager

   216      *         exists and the caller does not have

   217      *         ManagementPermission("control").

   218      *

   219      * @see #isThreadAllocatedMemorySupported

   220      */

   221     public void setThreadAllocatedMemoryEnabled(boolean enable);

   222 }