1 /*
  2  * Copyright (c) 2011, 2019, 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 public interface ThreadMXBean extends java.lang.management.ThreadMXBean {
 42     /**
 43      * Returns the total CPU time for each thread whose ID is
 44      * in the input array {@code ids} in nanoseconds.
 45      * The returned values are of nanoseconds precision but
 46      * not necessarily nanoseconds accuracy.
 47      * <p>
 48      * This method is equivalent to calling the
 49      * {@link ThreadMXBean#getThreadCpuTime(long)}
 50      * method for each thread ID in the input array {@code ids} and setting the
 51      * returned value in the corresponding element of the returned array.
 52      *
 53      * @param ids an array of thread IDs.
 54      * @return an array of long values, each of which is the amount of CPU
 55      * time the thread whose ID is in the corresponding element of the input
 56      * array of IDs has used,
 57      * if the thread of a specified ID exists, the thread is alive,
 58      * and CPU time measurement is enabled;
 59      * {@code -1} otherwise.
 60      *
 61      * @throws NullPointerException if {@code ids} is {@code null}
 62      * @throws IllegalArgumentException if any element in the input array
 63      *         {@code ids} is {@code <=} {@code 0}.
 64      * @throws UnsupportedOperationException if the Java
 65      *         virtual machine implementation does not support CPU time
 66      *         measurement.
 67      *
 68      * @see ThreadMXBean#getThreadCpuTime(long)
 69      * @see #getThreadUserTime
 70      * @see ThreadMXBean#isThreadCpuTimeSupported
 71      * @see ThreadMXBean#isThreadCpuTimeEnabled
 72      * @see ThreadMXBean#setThreadCpuTimeEnabled
 73      */
 74     public long[] getThreadCpuTime(long[] ids);
 75 
 76     /**
 77      * Returns the CPU time that each thread whose ID is in the input array
 78      * {@code ids} has executed in user mode in nanoseconds.
 79      * The returned values are of nanoseconds precision but
 80      * not necessarily nanoseconds accuracy.
 81      * <p>
 82      * This method is equivalent to calling the
 83      * {@link ThreadMXBean#getThreadUserTime(long)}
 84      * method for each thread ID in the input array {@code ids} and setting the
 85      * returned value in the corresponding element of the returned array.
 86      *
 87      * @param ids an array of thread IDs.
 88      * @return an array of long values, each of which is the amount of user
 89      * mode CPU time the thread whose ID is in the corresponding element of
 90      * the input array of IDs has used,
 91      * if the thread of a specified ID exists, the thread is alive,
 92      * and CPU time measurement is enabled;
 93      * {@code -1} otherwise.
 94      *
 95      * @throws NullPointerException if {@code ids} is {@code null}
 96      * @throws IllegalArgumentException if any element in the input array
 97      *         {@code ids} is {@code <=} {@code 0}.
 98      * @throws UnsupportedOperationException if the Java
 99      *         virtual machine implementation does not support CPU time
100      *         measurement.
101      *
102      * @see ThreadMXBean#getThreadUserTime(long)
103      * @see #getThreadCpuTime
104      * @see ThreadMXBean#isThreadCpuTimeSupported
105      * @see ThreadMXBean#isThreadCpuTimeEnabled
106      * @see ThreadMXBean#setThreadCpuTimeEnabled
107      */
108     public long[] getThreadUserTime(long[] ids);
109 
110     /**
111      * Returns an approximation of the total amount of memory, in bytes,
112      * allocated in heap memory for the current thread.
113      * The returned value is an approximation because some Java virtual machine
114      * implementations may use object allocation mechanisms that result in a
115      * delay between the time an object is allocated and the time its size is
116      * recorded.
117      *
118      * <p>
119      * This is a convenience method for local management use and is
120      * equivalent to calling:
121      * <blockquote><pre>
122      *   {@link #getThreadAllocatedBytes getThreadAllocatedBytes}(Thread.currentThread().getId());
123      * </pre></blockquote>
124      *
125      * @return an approximation of the total memory allocated, in bytes, in
126      * heap memory for the current thread
127      * if thread memory allocation measurement is enabled;
128      * {@code -1} otherwise.
129      *
130      * @throws UnsupportedOperationException if the Java virtual
131      *         machine implementation does not support thread memory allocation
132      *         measurement.
133      *
134      * @see #isThreadAllocatedMemorySupported
135      * @see #isThreadAllocatedMemoryEnabled
136      * @see #setThreadAllocatedMemoryEnabled
137      *
138      * @since 14
139      */
140     public default long getCurrentThreadAllocatedBytes() {
141         return getThreadAllocatedBytes(Thread.currentThread().getId());
142     }
143 
144     /**
145      * Returns an approximation of the total amount of memory, in bytes,
146      * allocated in heap memory for the thread with the specified ID.
147      * The returned value is an approximation because some Java virtual machine
148      * implementations may use object allocation mechanisms that result in a
149      * delay between the time an object is allocated and the time its size is
150      * recorded.
151      * <p>
152      * If the thread with the specified ID is a virtual thread, is not alive,
153      * or does not exist, this method returns {@code -1}. If thread memory
154      * allocation measurement is disabled, this method returns {@code -1}.
155      * A thread is alive if it has been started and has not yet terminated.
156      * <p>
157      * If thread memory allocation measurement is enabled after the thread has
158      * started, the Java virtual machine implementation may choose any time up
159      * to and including the time that the capability is enabled as the point
160      * where thread memory allocation measurement starts.
161      *
162      * @param id the thread ID of a thread
163      * @return an approximation of the total memory allocated, in bytes, in
164      * heap memory for the thread with the specified ID
165      * if the thread with the specified ID exists, the thread is alive,
166      * and thread memory allocation measurement is enabled;
167      * {@code -1} otherwise.
168      *
169      * @throws IllegalArgumentException if {@code id} {@code <=} {@code 0}.
170      * @throws UnsupportedOperationException if the Java virtual
171      *         machine implementation does not support thread memory allocation
172      *         measurement.
173      *
174      * @see #isThreadAllocatedMemorySupported
175      * @see #isThreadAllocatedMemoryEnabled
176      * @see #setThreadAllocatedMemoryEnabled
177      */
178     public long getThreadAllocatedBytes(long id);
179 
180     /**
181      * Returns an approximation of the total amount of memory, in bytes,
182      * allocated in heap memory for each thread whose ID is in the input
183      * array {@code ids}.
184      * The returned values are approximations because some Java virtual machine
185      * implementations may use object allocation mechanisms that result in a
186      * delay between the time an object is allocated and the time its size is
187      * recorded.
188      * <p>
189      * This method is equivalent to calling the
190      * {@link #getThreadAllocatedBytes(long)}
191      * method for each thread ID in the input array {@code ids} and setting the
192      * returned value in the corresponding element of the returned array.
193      *
194      * @param ids an array of thread IDs.
195      * @return an array of long values, each of which is an approximation of
196      * the total memory allocated, in bytes, in heap memory for the thread
197      * whose ID is in the corresponding element of the input array of IDs.
198      *
199      * @throws NullPointerException if {@code ids} is {@code null}
200      * @throws IllegalArgumentException if any element in the input array
201      *         {@code ids} is {@code <=} {@code 0}.
202      * @throws UnsupportedOperationException if the Java virtual
203      *         machine implementation does not support thread memory allocation
204      *         measurement.
205      *
206      * @see #getThreadAllocatedBytes(long)
207      * @see #isThreadAllocatedMemorySupported
208      * @see #isThreadAllocatedMemoryEnabled
209      * @see #setThreadAllocatedMemoryEnabled
210      */
211     public long[] getThreadAllocatedBytes(long[] ids);
212 
213     /**
214      * Tests if the Java virtual machine implementation supports thread memory
215      * allocation measurement.
216      *
217      * @return
218      *   {@code true}
219      *     if the Java virtual machine implementation supports thread memory
220      *     allocation measurement;
221      *   {@code false} otherwise.
222      */
223     public boolean isThreadAllocatedMemorySupported();
224 
225     /**
226      * Tests if thread memory allocation measurement is enabled.
227      *
228      * @return {@code true} if thread memory allocation measurement is enabled;
229      *         {@code false} otherwise.
230      *
231      * @throws UnsupportedOperationException if the Java virtual
232      *         machine does not support thread memory allocation measurement.
233      *
234      * @see #isThreadAllocatedMemorySupported
235      */
236     public boolean isThreadAllocatedMemoryEnabled();
237 
238     /**
239      * Enables or disables thread memory allocation measurement.  The default
240      * is platform dependent.
241      *
242      * @param enable {@code true} to enable;
243      *               {@code false} to disable.
244      *
245      * @throws UnsupportedOperationException if the Java virtual
246      *         machine does not support thread memory allocation measurement.
247      *
248      * @throws SecurityException if a security manager
249      *         exists and the caller does not have
250      *         ManagementPermission("control").
251      *
252      * @see #isThreadAllocatedMemorySupported
253      */
254     public void setThreadAllocatedMemoryEnabled(boolean enable);
255 }