+Overview +
+The supplied dates indicate when the API change was made, on the HG +default branch. From this you can generally tell whether the change should be +present in a given build or not; for trunk builds, simply whether it +was made before or after the change; for builds on a stabilization +branch, whether the branch was made before or after the given date. In +some cases corresponding API changes have been made both in the trunk +and in an in-progress stabilization branch, if they were needed for a +bug fix; this ought to be marked in this list.
+@FOOTER@
+ +
+
+ There will be tests to verify that the API works + as advertised. +
++ Currently NetBeans has sampling code part of core.ui module. There is + semi-API used by other modules like core, jumpto, editor.completion, + but it would be desirable to have real API in separate module. + So let's target this for inclusion in NetBeans 7.2 releases. +
+
+ Sampler.getGenericSampler(),
+ followed by
+ Sampler.start() and
+ Sampler.stop().
+
+ Sampler.getSampler(),
+ followed by
+ Sampler.start() and
+ Sampler.stopAndWriteTo(DataOutputStream dos).
+
+ It allows NetBeans Platform developer to self-sample their application, + which should provide them with a valuable information about CPU + performance problems. +
++ Yes, it is. +
+
+ This module replaces the previous semi-API
+ offered by core.ui module. Modules are now adviced
+ to depend just on the API exported by this module.
+
+ No standard is implemented by this module. +
++ XXX no answer for compat-version +
++ XXX no answer for dep-jre +
++ XXX no answer for dep-jrejdk +
++ None. +
++ There is no platform dependency. +
++ Nothing. +
++ XXX no answer for deploy-jar +
++ Yes, it can be deployed as NBM. +
++ XXX no answer for deploy-packages +
++ XXX no answer for deploy-shared +
++ XXX no answer for exec-ant-tasks +
++ XXX no answer for exec-classloader +
++ XXX no answer for exec-component +
++ XXX no answer for exec-introspection +
++ XXX no answer for exec-privateaccess +
++ XXX no answer for exec-process +
++ XXX no answer for exec-property +
++ XXX no answer for exec-reflection +
++ XXX no answer for exec-threading +
++ XXX no answer for format-clipboard +
++ XXX no answer for format-dnd +
++ XXX no answer for format-types +
++ XXX no answer for format-types +
++ XXX no answer for lookup-register +
++ XXX no answer for lookup-remove +
++ XXX no answer for perf-exit +
++ XXX no answer for perf-huge_dialogs +
++ XXX no answer for perf-limit +
++ XXX no answer for perf-mem +
++ XXX no answer for perf-menus +
++ XXX no answer for perf-progress +
++ XXX no answer for perf-scale +
++ XXX no answer for perf-spi +
++ XXX no answer for perf-startup +
++ XXX no answer for perf-wakeup +
++ XXX no answer for resources-file +
++ XXX no answer for resources-layer +
++ XXX no answer for resources-mask +
++ XXX no answer for resources-read +
++ XXX no answer for security-grant +
++ XXX no answer for security-policy +
++ XXX no answer for resources-preferences +
+null if the sampled application is in nonstandard mode
+ * which will produce unrealistic data - for example application is
+ * running under debugger or profiler.
+ * @param name which identifies the sampler thread
+ * @return instance of the {@link Sampler} or null if application
+ * is in nonstandard mode.
+ */
+ public static @CheckForNull Sampler getSampler(@NonNull String name) {
+ return InternalSampler.getInternalSampler(name);
+ }
+
+ /**
+ * Factory method for creating Sampler suitable for manual or user invoked
+ * scanning. This method can return null if it is running on
+ * some exotic variant of JDK, where sampling is not supported.
+ * @param name which identifies the sampler thread
+ * @return instance of the {@link Sampler} or null if sampling
+ * is not supported.
+ */
+ public static @CheckForNull Sampler getGenericSampler(@NonNull String name) {
+ if (SamplesOutputStream.isSupported()) {
+ return new InternalSampler(name);
+ }
+ return null;
+ }
+
Sampler(String n) {
name = n;
}
@@ -94,25 +123,25 @@
/** Returns the bean to use for sampling.
* @return instance of the bean to take thread dumps from
*/
- protected abstract ThreadMXBean getThreadMXBean();
+ abstract ThreadMXBean getThreadMXBean();
/** Allows subclasses to handle created snapshot
* @param arr the content of the snapshot
* @throws IOException thrown in case of I/O error
*/
- protected abstract void saveSnapshot(byte[] arr) throws IOException;
+ abstract void saveSnapshot(byte[] arr) throws IOException;
/** How to report an exception.
*
* @param ex exception
*/
- protected abstract void printStackTrace(Throwable ex);
+ abstract void printStackTrace(Throwable ex);
/** Methods for displaying progress.
*/
- protected abstract void openProgress(int steps);
- protected abstract void closeProgress();
- protected abstract void progress(int i);
+ abstract void openProgress(int steps);
+ abstract void closeProgress();
+ abstract void progress(int i);
private void updateStats(long timestamp) {
if (laststamp != 0) {
@@ -129,9 +158,13 @@
laststamp = timestamp;
}
- @Override
- public synchronized void run() {
- assert !running;
+ /**
+ * Start self-sampling. This method starts timer identified by name
+ * for actual sampling and returns immediately.
+ */
+ public synchronized void start() {
+ if (running) throw new IllegalStateException("sampling is already running"); // NOI18N
+ if (stopped) throw new IllegalStateException("it is not possible to restart sampling"); // NOI18N
running = true;
final ThreadMXBean threadBean = getThreadMXBean();
out = new ByteArrayOutputStream(64 * 1024);
@@ -165,21 +198,51 @@
}, SAMPLER_RATE, SAMPLER_RATE);
}
- @Override
- public synchronized void actionPerformed(ActionEvent e) {
+ /**
+ * Cancels the self-sampling. All sampled data are discarded.
+ */
+ public void cancel() {
+ stopSampling(true, null);
+ }
+
+ /**
+ * Stop the self-sampling started by {@link #start()} method and writes the data to
+ * {@link DataOutputStream}. If the internal sampling logic detects that
+ * the data are distorted for example due to heavy system I/O, collected
+ * samples are discarded and nothing is written to {@link DataOutputStream}.
+ *