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 } |
|