1fb3fb4f3Stomee /* 2fb3fb4f3Stomee * CDDL HEADER START 3fb3fb4f3Stomee * 4fb3fb4f3Stomee * The contents of this file are subject to the terms of the 5fb3fb4f3Stomee * Common Development and Distribution License (the "License"). 6fb3fb4f3Stomee * You may not use this file except in compliance with the License. 7fb3fb4f3Stomee * 8fb3fb4f3Stomee * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 9fb3fb4f3Stomee * or http://www.opensolaris.org/os/licensing. 10fb3fb4f3Stomee * See the License for the specific language governing permissions 11fb3fb4f3Stomee * and limitations under the License. 12fb3fb4f3Stomee * 13fb3fb4f3Stomee * When distributing Covered Code, include this CDDL HEADER in each 14fb3fb4f3Stomee * file and include the License file at usr/src/OPENSOLARIS.LICENSE. 15fb3fb4f3Stomee * If applicable, add the following below this CDDL HEADER, with the 16fb3fb4f3Stomee * fields enclosed by brackets "[]" replaced with your own identifying 17fb3fb4f3Stomee * information: Portions Copyright [yyyy] [name of copyright owner] 18fb3fb4f3Stomee * 19fb3fb4f3Stomee * CDDL HEADER END 20fb3fb4f3Stomee */ 21fb3fb4f3Stomee 22fb3fb4f3Stomee /* 2391cfa10aStomee * Copyright 2007 Sun Microsystems, Inc. All rights reserved. 24fb3fb4f3Stomee * Use is subject to license terms. 25fb3fb4f3Stomee */ 26fb3fb4f3Stomee package org.opensolaris.os.dtrace; 27fb3fb4f3Stomee 28fb3fb4f3Stomee import java.io.Serializable; 29fb3fb4f3Stomee import java.io.ObjectInputStream; 30fb3fb4f3Stomee import java.io.InvalidObjectException; 31fb3fb4f3Stomee import java.io.IOException; 32fb3fb4f3Stomee import java.beans.*; 33fb3fb4f3Stomee 34fb3fb4f3Stomee /** 35fb3fb4f3Stomee * A DTrace option and its value. Compile-time options must be set 36fb3fb4f3Stomee * before calling {@code Consumer} {@link Consumer#compile(String 37fb3fb4f3Stomee * program, String[] macroArgs) compile(String program, ...)} or {@link 38fb3fb4f3Stomee * Consumer#compile(File program, String[] macroArgs) compile(File 39fb3fb4f3Stomee * program, ...)} in order to affect program compilation. Runtime 40fb3fb4f3Stomee * options may be set anytime before calling {@code Consumer} {@link 41fb3fb4f3Stomee * Consumer#go() go()}, and some of them may be changed while a consumer 42fb3fb4f3Stomee * is running. 43fb3fb4f3Stomee * <p> 44fb3fb4f3Stomee * See the <a 453a931819SPeter Tribble * href=http://dtrace.org/guide/chp-opt.html> 463a931819SPeter Tribble * <b>Options and Tunables</b></a> chapter of the <i>Dynamic 47fb3fb4f3Stomee * Tracing Guide</i>. 48fb3fb4f3Stomee * <p> 49fb3fb4f3Stomee * Immutable. Supports persistence using {@link java.beans.XMLEncoder}. 50fb3fb4f3Stomee * 51fb3fb4f3Stomee * @author Tom Erickson 52fb3fb4f3Stomee */ 53fb3fb4f3Stomee public final class Option implements Serializable { 54fb3fb4f3Stomee static final long serialVersionUID = 2734100173861424920L; 55fb3fb4f3Stomee 56fb3fb4f3Stomee /** 57fb3fb4f3Stomee * Value returned by {@link Consumer#getOption(String option)} when 58fb3fb4f3Stomee * the given boolean option is unset. 59fb3fb4f3Stomee */ 60fb3fb4f3Stomee public static final long UNSET = -2L; 61fb3fb4f3Stomee 62fb3fb4f3Stomee /** 63fb3fb4f3Stomee * Value returned by {@link Consumer#getOption(String option)} for 64fb3fb4f3Stomee * the {@link #bufpolicy} option when the {@link #VALUE_RING ring} 65fb3fb4f3Stomee * buffer policy is set. 66fb3fb4f3Stomee */ 67fb3fb4f3Stomee public static final long BUFPOLICY_RING = 0L; 68fb3fb4f3Stomee 69fb3fb4f3Stomee /** 70fb3fb4f3Stomee * Value returned by {@link Consumer#getOption(String option)} for 71fb3fb4f3Stomee * the {@link #bufpolicy} option when the {@link #VALUE_FILL fill} 72fb3fb4f3Stomee * buffer policy is set. 73fb3fb4f3Stomee */ 74fb3fb4f3Stomee public static final long BUFPOLICY_FILL = 1L; 75fb3fb4f3Stomee 76fb3fb4f3Stomee /** 77fb3fb4f3Stomee * Value returned by {@link Consumer#getOption(String option)} for 78fb3fb4f3Stomee * the {@link #bufpolicy} option when the default {@link 79fb3fb4f3Stomee * #VALUE_SWITCH switch} buffer policy is set. 80fb3fb4f3Stomee */ 81fb3fb4f3Stomee public static final long BUFPOLICY_SWITCH = 2L; 82fb3fb4f3Stomee 83fb3fb4f3Stomee /** 84fb3fb4f3Stomee * Value returned by {@link Consumer#getOption(String option)} for 85fb3fb4f3Stomee * the {@link #bufresize} option when the default {@link #VALUE_AUTO 86fb3fb4f3Stomee * auto} buffer resize policy is set. 87fb3fb4f3Stomee */ 88fb3fb4f3Stomee public static final long BUFRESIZE_AUTO = 0L; 89fb3fb4f3Stomee 90fb3fb4f3Stomee /** 91fb3fb4f3Stomee * Value returned by {@link Consumer#getOption(String option)} for 92fb3fb4f3Stomee * the {@link #bufresize} option when the {@link #VALUE_MANUAL 93fb3fb4f3Stomee * manual} buffer resize policy is set. 94fb3fb4f3Stomee */ 95fb3fb4f3Stomee public static final long BUFRESIZE_MANUAL = 1L; 96fb3fb4f3Stomee 97fb3fb4f3Stomee static { 98fb3fb4f3Stomee try { 99fb3fb4f3Stomee BeanInfo info = Introspector.getBeanInfo(Option.class); 100fb3fb4f3Stomee PersistenceDelegate persistenceDelegate = 101fb3fb4f3Stomee new DefaultPersistenceDelegate( 10252aacb45Stomee new String[] {"name", "value"}) 103fb3fb4f3Stomee { 104fb3fb4f3Stomee /* 105fb3fb4f3Stomee * Need to prevent DefaultPersistenceDelegate from using 106fb3fb4f3Stomee * overridden equals() method, resulting in a 107fb3fb4f3Stomee * StackOverFlowError. Revert to PersistenceDelegate 108fb3fb4f3Stomee * implementation. See 109fb3fb4f3Stomee * http://forum.java.sun.com/thread.jspa?threadID= 110fb3fb4f3Stomee * 477019&tstart=135 111fb3fb4f3Stomee */ 112fb3fb4f3Stomee protected boolean 113fb3fb4f3Stomee mutatesTo(Object oldInstance, Object newInstance) 114fb3fb4f3Stomee { 115fb3fb4f3Stomee return (newInstance != null && oldInstance != null && 116fb3fb4f3Stomee oldInstance.getClass() == newInstance.getClass()); 117fb3fb4f3Stomee } 118fb3fb4f3Stomee }; 119fb3fb4f3Stomee BeanDescriptor d = info.getBeanDescriptor(); 120fb3fb4f3Stomee d.setValue("persistenceDelegate", persistenceDelegate); 121fb3fb4f3Stomee } catch (IntrospectionException e) { 122fb3fb4f3Stomee System.out.println(e); 123fb3fb4f3Stomee } 124fb3fb4f3Stomee } 125fb3fb4f3Stomee 126fb3fb4f3Stomee // 127fb3fb4f3Stomee // See lib/libdtrace/common/dt_options.c 128fb3fb4f3Stomee // 129fb3fb4f3Stomee 130fb3fb4f3Stomee /** 131fb3fb4f3Stomee * Gets a size option value indicating the given number of 132fb3fb4f3Stomee * kilobytes. 133fb3fb4f3Stomee * 134fb3fb4f3Stomee * @param n number of kilobytes 135fb3fb4f3Stomee * @return size option value indicating the given number of 136fb3fb4f3Stomee * kilobytes 137fb3fb4f3Stomee */ 138fb3fb4f3Stomee public static String kb(int n)139fb3fb4f3Stomee kb(int n) 140fb3fb4f3Stomee { 141fb3fb4f3Stomee return (Integer.toString(n) + "k"); 142fb3fb4f3Stomee } 143fb3fb4f3Stomee 144fb3fb4f3Stomee /** 145fb3fb4f3Stomee * Gets a size option value indicating the given number of 146fb3fb4f3Stomee * megabytes. 147fb3fb4f3Stomee * 148fb3fb4f3Stomee * @param n number of megabytes 149fb3fb4f3Stomee * @return size option value indicating the given number of 150fb3fb4f3Stomee * megabytes 151fb3fb4f3Stomee */ 152fb3fb4f3Stomee public static String mb(int n)153fb3fb4f3Stomee mb(int n) 154fb3fb4f3Stomee { 155fb3fb4f3Stomee return (Integer.toString(n) + "m"); 156fb3fb4f3Stomee } 157fb3fb4f3Stomee 158fb3fb4f3Stomee /** 159fb3fb4f3Stomee * Gets a size option value indicating the given number of 160fb3fb4f3Stomee * gigabytes. 161fb3fb4f3Stomee * 162fb3fb4f3Stomee * @param n number of gigabytes 163fb3fb4f3Stomee * @return size option value indicating the given number of 164fb3fb4f3Stomee * gigabytes 165fb3fb4f3Stomee */ 166fb3fb4f3Stomee public static String gb(int n)167fb3fb4f3Stomee gb(int n) 168fb3fb4f3Stomee { 169fb3fb4f3Stomee return (Integer.toString(n) + "g"); 170fb3fb4f3Stomee } 171fb3fb4f3Stomee 172fb3fb4f3Stomee /** 173fb3fb4f3Stomee * Gets a size option value indicating the given number of 174fb3fb4f3Stomee * terabytes. 175fb3fb4f3Stomee * 176fb3fb4f3Stomee * @param n number of terabytes 177fb3fb4f3Stomee * @return size option value indicating the given number of 178fb3fb4f3Stomee * terabytes 179fb3fb4f3Stomee */ 180fb3fb4f3Stomee public static String tb(int n)181fb3fb4f3Stomee tb(int n) 182fb3fb4f3Stomee { 183fb3fb4f3Stomee return (Integer.toString(n) + "t"); 184fb3fb4f3Stomee } 185fb3fb4f3Stomee 186fb3fb4f3Stomee /** 187fb3fb4f3Stomee * Gets a time option value indicating the given number of 188fb3fb4f3Stomee * nanoseconds. 189fb3fb4f3Stomee * 190fb3fb4f3Stomee * @param n number of nanoseconds 191fb3fb4f3Stomee * @return time option value indicating the given number of 192fb3fb4f3Stomee * nanoseconds 193fb3fb4f3Stomee */ 194fb3fb4f3Stomee public static String nanos(int n)195fb3fb4f3Stomee nanos(int n) 196fb3fb4f3Stomee { 197fb3fb4f3Stomee return (Integer.toString(n) + "ns"); 198fb3fb4f3Stomee } 199fb3fb4f3Stomee 200fb3fb4f3Stomee /** 201fb3fb4f3Stomee * Gets a time option value indicating the given number of 202fb3fb4f3Stomee * microseconds. 203fb3fb4f3Stomee * 204fb3fb4f3Stomee * @param n number of microseconds 205fb3fb4f3Stomee * @return time option value indicating the given number of 206fb3fb4f3Stomee * microseconds 207fb3fb4f3Stomee */ 208fb3fb4f3Stomee public static String micros(int n)209fb3fb4f3Stomee micros(int n) 210fb3fb4f3Stomee { 211fb3fb4f3Stomee return (Integer.toString(n) + "us"); 212fb3fb4f3Stomee } 213fb3fb4f3Stomee 214fb3fb4f3Stomee /** 215fb3fb4f3Stomee * Gets a time option value indicating the given number of 216fb3fb4f3Stomee * milliseconds. 217fb3fb4f3Stomee * 218fb3fb4f3Stomee * @param n number of milliseconds 219fb3fb4f3Stomee * @return time option value indicating the given number of 220fb3fb4f3Stomee * milliseconds 221fb3fb4f3Stomee */ 222fb3fb4f3Stomee public static String millis(int n)223fb3fb4f3Stomee millis(int n) 224fb3fb4f3Stomee { 225fb3fb4f3Stomee return (Integer.toString(n) + "ms"); 226fb3fb4f3Stomee } 227fb3fb4f3Stomee 228fb3fb4f3Stomee /** 229fb3fb4f3Stomee * Gets a time option value indicating the given number of seconds. 230fb3fb4f3Stomee * 231fb3fb4f3Stomee * @param n number of seconds 232fb3fb4f3Stomee * @return time option value indicating the given number of seconds 233fb3fb4f3Stomee */ 234fb3fb4f3Stomee public static String seconds(int n)235fb3fb4f3Stomee seconds(int n) 236fb3fb4f3Stomee { 237fb3fb4f3Stomee return (Integer.toString(n) + "s"); 238fb3fb4f3Stomee } 239fb3fb4f3Stomee 240fb3fb4f3Stomee /** 241fb3fb4f3Stomee * Gets a time option value indicating the given number of minutes. 242fb3fb4f3Stomee * 243fb3fb4f3Stomee * @param n number of minutes 244fb3fb4f3Stomee * @return time option value indicating the given number of minutes 245fb3fb4f3Stomee */ 246fb3fb4f3Stomee public static String minutes(int n)247fb3fb4f3Stomee minutes(int n) 248fb3fb4f3Stomee { 249fb3fb4f3Stomee return (Integer.toString(n) + "m"); 250fb3fb4f3Stomee } 251fb3fb4f3Stomee 252fb3fb4f3Stomee /** 253fb3fb4f3Stomee * Gets a time option value indicating the given number of hours. 254fb3fb4f3Stomee * 255fb3fb4f3Stomee * @param n number of hours 256fb3fb4f3Stomee * @return time option value indicating the given number of hours 257fb3fb4f3Stomee */ 258fb3fb4f3Stomee public static String hours(int n)259fb3fb4f3Stomee hours(int n) 260fb3fb4f3Stomee { 261fb3fb4f3Stomee return (Integer.toString(n) + "h"); 262fb3fb4f3Stomee } 263fb3fb4f3Stomee 264fb3fb4f3Stomee /** 265fb3fb4f3Stomee * Gets a time option value indicating the given number of days. 266fb3fb4f3Stomee * 267fb3fb4f3Stomee * @param n number of days 268fb3fb4f3Stomee * @return time option value indicating the given number of days 269fb3fb4f3Stomee */ 270fb3fb4f3Stomee public static String days(int n)271fb3fb4f3Stomee days(int n) 272fb3fb4f3Stomee { 273fb3fb4f3Stomee return (Integer.toString(n) + "d"); 274fb3fb4f3Stomee } 275fb3fb4f3Stomee 276fb3fb4f3Stomee /** 277fb3fb4f3Stomee * Gets a time option value indicating the given rate per second. 278fb3fb4f3Stomee * 279fb3fb4f3Stomee * @param n number of cycles per second (hertz) 280fb3fb4f3Stomee * @return time option value indicating rate per second 281fb3fb4f3Stomee */ 282fb3fb4f3Stomee public static String hz(int n)283fb3fb4f3Stomee hz(int n) 284fb3fb4f3Stomee { 285fb3fb4f3Stomee return (Integer.toString(n) + "hz"); 286fb3fb4f3Stomee } 287fb3fb4f3Stomee 288fb3fb4f3Stomee /** 289fb3fb4f3Stomee * May be passed to {@link Consumer#setOption(String option, String 290fb3fb4f3Stomee * value)} to set a boolean option such as {@link #flowindent}. 291fb3fb4f3Stomee * However, a more convenient way to set boolean options is {@link 292fb3fb4f3Stomee * Consumer#setOption(String option)}. 293fb3fb4f3Stomee */ 294fb3fb4f3Stomee public static final String VALUE_SET = "set"; 295fb3fb4f3Stomee 296fb3fb4f3Stomee /** 297fb3fb4f3Stomee * May be passed to {@link Consumer#setOption(String option, String 298fb3fb4f3Stomee * value)} to unset a boolean option such as {@link #flowindent}. 299fb3fb4f3Stomee * However, a more convenient way to unset boolean options is {@link 300fb3fb4f3Stomee * Consumer#unsetOption(String option)}. 301fb3fb4f3Stomee */ 302fb3fb4f3Stomee public static final String VALUE_UNSET = "unset"; 303fb3fb4f3Stomee 304fb3fb4f3Stomee /** 3053a931819SPeter Tribble * {@link #bufpolicy} value: use {@code ring} principal buffer 306fb3fb4f3Stomee * policy. 307fb3fb4f3Stomee */ 308fb3fb4f3Stomee public static final String VALUE_RING = "ring"; 309fb3fb4f3Stomee /** 3103a931819SPeter Tribble * {@link #bufpolicy} value: use {@code fill} principal buffer 311fb3fb4f3Stomee * policy. 312fb3fb4f3Stomee */ 313fb3fb4f3Stomee public static final String VALUE_FILL = "fill"; 314fb3fb4f3Stomee /** 3153a931819SPeter Tribble * {@link #bufpolicy} default value: use {@code switch} principal 316fb3fb4f3Stomee * buffer policy. 317fb3fb4f3Stomee */ 318fb3fb4f3Stomee public static final String VALUE_SWITCH = "switch"; 319fb3fb4f3Stomee 320fb3fb4f3Stomee /** 321fb3fb4f3Stomee * {@link #bufresize} default value: use {@code auto} buffer 322fb3fb4f3Stomee * resizing policy. 323fb3fb4f3Stomee */ 324fb3fb4f3Stomee public static final String VALUE_AUTO = "auto"; 325fb3fb4f3Stomee /** 326fb3fb4f3Stomee * {@link #bufresize} value: use {@code manual} buffer resizing 327fb3fb4f3Stomee * policy. 328fb3fb4f3Stomee */ 329fb3fb4f3Stomee public static final String VALUE_MANUAL = "manual"; 330fb3fb4f3Stomee 331fb3fb4f3Stomee // 332fb3fb4f3Stomee // See lib/libdtrace/common/dt_options.c 333fb3fb4f3Stomee // 334fb3fb4f3Stomee 335fb3fb4f3Stomee /** 336fb3fb4f3Stomee * Set program attribute minimum (compile-time). The format of the 337fb3fb4f3Stomee * option value is defined by the {@link 338fb3fb4f3Stomee * InterfaceAttributes#toString()} method. 339fb3fb4f3Stomee * 340fb3fb4f3Stomee * @see Program#getInfo() 341fb3fb4f3Stomee */ 342fb3fb4f3Stomee public static final String amin = "amin"; 343fb3fb4f3Stomee /** 344fb3fb4f3Stomee * Do not require all macro args to be used (compile-time; no option 345fb3fb4f3Stomee * value). 346fb3fb4f3Stomee * 347fb3fb4f3Stomee * @see Consumer#compile(String program, String[] macroArgs) 348fb3fb4f3Stomee * @see Consumer#compile(File program, String[] macroArgs) 349fb3fb4f3Stomee */ 350fb3fb4f3Stomee public static final String argref = "argref"; 351fb3fb4f3Stomee /** 352fb3fb4f3Stomee * Run cpp(1) preprocessor on D script files (compile-time; no 353fb3fb4f3Stomee * option value). 354fb3fb4f3Stomee */ 355fb3fb4f3Stomee public static final String cpp = "cpp"; 356fb3fb4f3Stomee /** 357fb3fb4f3Stomee * Used together with {@link #cpp} option, specifies which {@code 358fb3fb4f3Stomee * cpp} to run by its pathname (compile-time). 359fb3fb4f3Stomee */ 360fb3fb4f3Stomee public static final String cpppath = "cpppath"; 361fb3fb4f3Stomee /** 362fb3fb4f3Stomee * Use zero (0) or empty string ("") as the value for unspecified macro args 363fb3fb4f3Stomee * (compile-time; no option value). 364fb3fb4f3Stomee * 365fb3fb4f3Stomee * @see Consumer#compile(String program, String[] macroArgs) 366fb3fb4f3Stomee * @see Consumer#compile(File program, String[] macroArgs) 367fb3fb4f3Stomee */ 368fb3fb4f3Stomee public static final String defaultargs = "defaultargs"; 369fb3fb4f3Stomee /** 3703a931819SPeter Tribble * Define symbol when invoking preprocessor (compile-time). 371fb3fb4f3Stomee */ 372fb3fb4f3Stomee public static final String define = "define"; 373fb3fb4f3Stomee /** 374fb3fb4f3Stomee * Permit compilation of empty D source files (compile-time; no 375fb3fb4f3Stomee * option value). 376fb3fb4f3Stomee */ 377fb3fb4f3Stomee public static final String empty = "empty"; 378fb3fb4f3Stomee /** 379fb3fb4f3Stomee * Adds error tags to default error messages (compile-time; no 380fb3fb4f3Stomee * option value). 381fb3fb4f3Stomee */ 382fb3fb4f3Stomee public static final String errtags = "errtags"; 383fb3fb4f3Stomee /** 384fb3fb4f3Stomee * Add include directory to preprocessor search path (compile-time). 385fb3fb4f3Stomee */ 386fb3fb4f3Stomee public static final String incdir = "incdir"; 387fb3fb4f3Stomee /** 388fb3fb4f3Stomee * Permit unresolved kernel symbols (compile-time; no option value). 389fb3fb4f3Stomee */ 390fb3fb4f3Stomee public static final String knodefs = "knodefs"; 391fb3fb4f3Stomee /** 392fb3fb4f3Stomee * Add library directory to library search path (compile-time). 393fb3fb4f3Stomee */ 394fb3fb4f3Stomee public static final String libdir = "libdir"; 395fb3fb4f3Stomee /** 396fb3fb4f3Stomee * Specify ISO C conformance settings for preprocessor 397fb3fb4f3Stomee * (compile-time). 398fb3fb4f3Stomee */ 399fb3fb4f3Stomee public static final String stdc = "stdc"; 400fb3fb4f3Stomee /** 401fb3fb4f3Stomee * Undefine symbol when invoking preprocessor (compile-time). 402fb3fb4f3Stomee */ 403fb3fb4f3Stomee public static final String undef = "undef"; 404fb3fb4f3Stomee /** 405fb3fb4f3Stomee * Permit unresolved user symbols (compile-time; no option value). 406fb3fb4f3Stomee */ 407fb3fb4f3Stomee public static final String unodefs = "unodefs"; 408fb3fb4f3Stomee /** 409fb3fb4f3Stomee * Request specific version of native DTrace library (compile-time). 410fb3fb4f3Stomee */ 411fb3fb4f3Stomee public static final String version = "version"; 412fb3fb4f3Stomee /** 413fb3fb4f3Stomee * Permit probe definitions that match zero probes (compile-time; no 414fb3fb4f3Stomee * option value). 415fb3fb4f3Stomee */ 416fb3fb4f3Stomee public static final String zdefs = "zdefs"; 417fb3fb4f3Stomee 418fb3fb4f3Stomee /** Rate of aggregation reading (time). Runtime option. */ 419fb3fb4f3Stomee public static final String aggrate = "aggrate"; 420fb3fb4f3Stomee /** Aggregation buffer size (size). Runtime option. */ 421fb3fb4f3Stomee public static final String aggsize = "aggsize"; 422fb3fb4f3Stomee /** 423fb3fb4f3Stomee * Denotes that aggregation data should be sorted in tuple order, 424fb3fb4f3Stomee * with ties broken by value order (no option value). Runtime 425fb3fb4f3Stomee * option. 426fb3fb4f3Stomee * 427fb3fb4f3Stomee * @see AggregationRecord 428fb3fb4f3Stomee * @see Option#aggsortkeypos 429fb3fb4f3Stomee * @see Option#aggsortpos 430fb3fb4f3Stomee * @see Option#aggsortrev 431fb3fb4f3Stomee */ 432fb3fb4f3Stomee public static final String aggsortkey = "aggsortkey"; 433fb3fb4f3Stomee /** 434fb3fb4f3Stomee * When multiple aggregation tuple elements are present, the 435fb3fb4f3Stomee * position of the tuple element that should act as the primary sort 436fb3fb4f3Stomee * key (zero-based index). Runtime option. 437fb3fb4f3Stomee * 438fb3fb4f3Stomee * @see Option#aggsortkey 439fb3fb4f3Stomee * @see Option#aggsortpos 440fb3fb4f3Stomee * @see Option#aggsortrev 441fb3fb4f3Stomee */ 442fb3fb4f3Stomee public static final String aggsortkeypos = "aggsortkeypos"; 443fb3fb4f3Stomee /** 444fb3fb4f3Stomee * When multiple aggregations are being printed, the position of the 445fb3fb4f3Stomee * aggregation that should act as the primary sort key (zero-based 446fb3fb4f3Stomee * index). Runtime option. 447fb3fb4f3Stomee * <p> 448fb3fb4f3Stomee * Here "position" refers to the position of the aggregation in the 449fb3fb4f3Stomee * {@code printa()} argument list after the format string (if 450fb3fb4f3Stomee * any). For example, given the following statement: 451fb3fb4f3Stomee * <pre><code> 452fb3fb4f3Stomee * printa("%d %@7d %@7d\n", @a, @b); 453fb3fb4f3Stomee * </code></pre> 454fb3fb4f3Stomee * setting {@code aggsortpos} to {@code "0"} indicates that output 455fb3fb4f3Stomee * should be sorted using the values of {@code @a} as the primary 456fb3fb4f3Stomee * sort key, while setting {@code aggsortpos} to {@code "1"} 457fb3fb4f3Stomee * indicates that output should be sorted using the values of 458fb3fb4f3Stomee * {@code @b} as the primary sort key. 459fb3fb4f3Stomee * 460fb3fb4f3Stomee * @see Option#aggsortkey 461fb3fb4f3Stomee * @see Option#aggsortkeypos 462fb3fb4f3Stomee * @see Option#aggsortrev 463fb3fb4f3Stomee */ 464fb3fb4f3Stomee public static final String aggsortpos = "aggsortpos"; 465fb3fb4f3Stomee /** 466fb3fb4f3Stomee * Denotes that aggregation data should be sorted in descending 467fb3fb4f3Stomee * order (no option value). Runtime option. 468fb3fb4f3Stomee * <p> 469fb3fb4f3Stomee * The {@code aggsortrev} option is useful in combination with the 470fb3fb4f3Stomee * {@code aggsortkey}, {@code aggsortkeypos}, and {@code aggsortpos} 471fb3fb4f3Stomee * options, which define the ascending sort reversed by this option. 472fb3fb4f3Stomee * 473fb3fb4f3Stomee * @see Option#aggsortkey 474fb3fb4f3Stomee * @see Option#aggsortkeypos 475fb3fb4f3Stomee * @see Option#aggsortpos 476fb3fb4f3Stomee */ 477fb3fb4f3Stomee public static final String aggsortrev = "aggsortrev"; 478fb3fb4f3Stomee /** Principal buffer size (size). Runtime option. */ 479fb3fb4f3Stomee public static final String bufsize = "bufsize"; 480fb3fb4f3Stomee /** 481fb3fb4f3Stomee * Buffering policy ({@link #VALUE_SWITCH switch}, {@link 482fb3fb4f3Stomee * #VALUE_FILL fill}, or {@link #VALUE_RING ring}). Runtime option. 483fb3fb4f3Stomee * <p> 484fb3fb4f3Stomee * See the <a 4853a931819SPeter Tribble * href=http://dtrace.org/guide/chp-buf.html#chp-buf-2> 486fb3fb4f3Stomee * <b>Principal Buffer Policies</b></a> section of the 4873a931819SPeter Tribble * <b>Buffers and Buffering</b> chapter of the <i>Dynamic 488fb3fb4f3Stomee * Tracing Guide</i>. 489fb3fb4f3Stomee */ 490fb3fb4f3Stomee public static final String bufpolicy = "bufpolicy"; 491fb3fb4f3Stomee /** 492fb3fb4f3Stomee * Buffer resizing policy ({@link #VALUE_AUTO auto} or {@link 493fb3fb4f3Stomee * #VALUE_MANUAL manual}). Runtime option. 494fb3fb4f3Stomee * <p> 495fb3fb4f3Stomee * See the <a 4963a931819SPeter Tribble * href=http://dtrace.org/guide/chp-buf.html#chp-buf-5> 497fb3fb4f3Stomee * <b>Buffer Resizing Policy</b></a> section of the <b>Buffers 4983a931819SPeter Tribble * and Buffering</b> chapter of the <i>Dynamic Tracing 499fb3fb4f3Stomee * Guide</i>. 500fb3fb4f3Stomee */ 501fb3fb4f3Stomee public static final String bufresize = "bufresize"; 502fb3fb4f3Stomee /** Cleaning rate (time). Runtime option. */ 503fb3fb4f3Stomee public static final String cleanrate = "cleanrate"; 504fb3fb4f3Stomee /** CPU on which to enable tracing (scalar). Runtime option. */ 505fb3fb4f3Stomee public static final String cpu = "cpu"; 506fb3fb4f3Stomee /** Permit destructive actions (no option value). Runtime option. */ 507fb3fb4f3Stomee public static final String destructive = "destructive"; 508fb3fb4f3Stomee /** Dynamic variable space size (size). Runtime option. */ 509fb3fb4f3Stomee public static final String dynvarsize = "dynvarsize"; 510fb3fb4f3Stomee /** 511fb3fb4f3Stomee * Adds {@link Flow} information to generated {@link ProbeData} 512fb3fb4f3Stomee * indicating direction of control flow (entry or return) across 513fb3fb4f3Stomee * function boundaries and depth in call stack (no option value). 514fb3fb4f3Stomee * Runtime option. 515fb3fb4f3Stomee */ 516fb3fb4f3Stomee public static final String flowindent = "flowindent"; 517fb3fb4f3Stomee /** Number of speculations (scalar). Runtime option. */ 518fb3fb4f3Stomee public static final String nspec = "nspec"; 519fb3fb4f3Stomee /** 520fb3fb4f3Stomee * Only output explicitly traced data (no option value). Makes no 521fb3fb4f3Stomee * difference to generated {@link ProbeData}, but user apps may use 522fb3fb4f3Stomee * the {@code quiet} flag as a rendering hint similar to the {@code 523*bbf21555SRichard Lowe * -q} {@code dtrace(8)} command option. Runtime option. 524fb3fb4f3Stomee */ 525fb3fb4f3Stomee public static final String quiet = "quiet"; 526fb3fb4f3Stomee /** Speculation buffer size (size). Runtime option. */ 527fb3fb4f3Stomee public static final String specsize = "specsize"; 528fb3fb4f3Stomee /** Number of stack frames (scalar). Runtime option. */ 529fb3fb4f3Stomee public static final String stackframes = "stackframes"; 530fb3fb4f3Stomee /** Rate of status checking (time). Runtime option. */ 531fb3fb4f3Stomee public static final String statusrate = "statusrate"; 532fb3fb4f3Stomee /** String size (size). Runtime option. */ 533fb3fb4f3Stomee public static final String strsize = "strsize"; 534fb3fb4f3Stomee /** Rate of buffer switching (time). Runtime option. */ 535fb3fb4f3Stomee public static final String switchrate = "switchrate"; 536fb3fb4f3Stomee /** Number of user stack frames (scalar). Runtime option. */ 537fb3fb4f3Stomee public static final String ustackframes = "ustackframes"; 538fb3fb4f3Stomee 539fb3fb4f3Stomee /** @serial */ 54052aacb45Stomee private final String name; 541fb3fb4f3Stomee /** @serial */ 542fb3fb4f3Stomee private final String value; 543fb3fb4f3Stomee 544fb3fb4f3Stomee /** 545fb3fb4f3Stomee * Creates an option without an associated value. The created 546fb3fb4f3Stomee * boolean option has the value {@link Option#VALUE_SET}. To 547fb3fb4f3Stomee * specify that the named option be unset, use {@link 548fb3fb4f3Stomee * Option#VALUE_UNSET}. 549fb3fb4f3Stomee * 55052aacb45Stomee * @param optionName DTrace option name 551fb3fb4f3Stomee * @throws NullPointerException if the given option name is {@code 552fb3fb4f3Stomee * null} 55352aacb45Stomee * @see #Option(String optionName, String optionValue) 554fb3fb4f3Stomee */ 555fb3fb4f3Stomee public Option(String optionName)55652aacb45Stomee Option(String optionName) 557fb3fb4f3Stomee { 55852aacb45Stomee this(optionName, Option.VALUE_SET); 559fb3fb4f3Stomee } 560fb3fb4f3Stomee 561fb3fb4f3Stomee /** 562fb3fb4f3Stomee * Creates an option with the given name and value. 563fb3fb4f3Stomee * 56452aacb45Stomee * @param optionName DTrace option name 56552aacb45Stomee * @param optionValue DTrace option value 566fb3fb4f3Stomee * @throws NullPointerException if the given option name or value is 567fb3fb4f3Stomee * {@code null} 568fb3fb4f3Stomee */ 569fb3fb4f3Stomee public Option(String optionName, String optionValue)57052aacb45Stomee Option(String optionName, String optionValue) 571fb3fb4f3Stomee { 57252aacb45Stomee name = optionName; 57352aacb45Stomee value = optionValue; 574fb3fb4f3Stomee validate(); 575fb3fb4f3Stomee } 576fb3fb4f3Stomee 57791cfa10aStomee private final void validate()578fb3fb4f3Stomee validate() 579fb3fb4f3Stomee { 58052aacb45Stomee if (name == null) { 581fb3fb4f3Stomee throw new NullPointerException("option name is null"); 582fb3fb4f3Stomee } 583fb3fb4f3Stomee if (value == null) { 584fb3fb4f3Stomee throw new NullPointerException("option value is null"); 585fb3fb4f3Stomee } 586fb3fb4f3Stomee } 587fb3fb4f3Stomee 588fb3fb4f3Stomee /** 589fb3fb4f3Stomee * Gets the option name. 590fb3fb4f3Stomee * 591fb3fb4f3Stomee * @return non-null option name 592fb3fb4f3Stomee */ 593fb3fb4f3Stomee public String getName()59452aacb45Stomee getName() 595fb3fb4f3Stomee { 59652aacb45Stomee return name; 597fb3fb4f3Stomee } 598fb3fb4f3Stomee 599fb3fb4f3Stomee /** 600fb3fb4f3Stomee * Gets the option value. 601fb3fb4f3Stomee * 602fb3fb4f3Stomee * @return option value, or {@code null} if no value is associated 603fb3fb4f3Stomee * with the option 604fb3fb4f3Stomee */ 605fb3fb4f3Stomee public String getValue()606fb3fb4f3Stomee getValue() 607fb3fb4f3Stomee { 608fb3fb4f3Stomee return value; 609fb3fb4f3Stomee } 610fb3fb4f3Stomee 611fb3fb4f3Stomee /** 612fb3fb4f3Stomee * Compares the specified object with this option for equality. 613fb3fb4f3Stomee * Defines equality as having equal names and values. 614fb3fb4f3Stomee * 615fb3fb4f3Stomee * @return {@code true} if and only if the specified object is an 616fb3fb4f3Stomee * {@code Option} with the same name and the same value as this 617fb3fb4f3Stomee * option. Option values are the same if they are both {@code null} 618fb3fb4f3Stomee * or if they are equal as defined by {@link String#equals(Object o) 619fb3fb4f3Stomee * String.equals()}. 620fb3fb4f3Stomee */ 621fb3fb4f3Stomee public boolean equals(Object o)622fb3fb4f3Stomee equals(Object o) 623fb3fb4f3Stomee { 624fb3fb4f3Stomee if (o instanceof Option) { 625fb3fb4f3Stomee Option opt = (Option)o; 62652aacb45Stomee return (name.equals(opt.name) && 627fb3fb4f3Stomee value.equals(opt.value)); 628fb3fb4f3Stomee } 629fb3fb4f3Stomee return false; 630fb3fb4f3Stomee } 631fb3fb4f3Stomee 632fb3fb4f3Stomee /** 633fb3fb4f3Stomee * Overridden to ensure that equal options have equal hashcodes. 634fb3fb4f3Stomee */ 635fb3fb4f3Stomee @Override 636fb3fb4f3Stomee public int hashCode()637fb3fb4f3Stomee hashCode() 638fb3fb4f3Stomee { 639fb3fb4f3Stomee int hash = 17; 64052aacb45Stomee hash = (37 * hash) + name.hashCode(); 641fb3fb4f3Stomee hash = (37 * hash) + value.hashCode(); 642fb3fb4f3Stomee return hash; 643fb3fb4f3Stomee } 644fb3fb4f3Stomee 645fb3fb4f3Stomee private void readObject(ObjectInputStream s)646fb3fb4f3Stomee readObject(ObjectInputStream s) 647fb3fb4f3Stomee throws IOException, ClassNotFoundException 648fb3fb4f3Stomee { 649fb3fb4f3Stomee s.defaultReadObject(); 650fb3fb4f3Stomee // check invariants 651fb3fb4f3Stomee try { 652fb3fb4f3Stomee validate(); 653fb3fb4f3Stomee } catch (Exception e) { 6544ae67516Stomee InvalidObjectException x = new InvalidObjectException( 6554ae67516Stomee e.getMessage()); 6564ae67516Stomee x.initCause(e); 6574ae67516Stomee throw x; 658fb3fb4f3Stomee } 659fb3fb4f3Stomee } 660fb3fb4f3Stomee 661fb3fb4f3Stomee /** 662fb3fb4f3Stomee * Gets a string representation of this option useful for logging 663fb3fb4f3Stomee * and not intended for display. The exact details of the 664fb3fb4f3Stomee * representation are unspecified and subject to change, but the 665fb3fb4f3Stomee * following format may be regarded as typical: 666fb3fb4f3Stomee * <pre><code> 667fb3fb4f3Stomee * class-name[property1 = value1, property2 = value2] 668fb3fb4f3Stomee * </code></pre> 669fb3fb4f3Stomee */ 670fb3fb4f3Stomee public String toString()671fb3fb4f3Stomee toString() 672fb3fb4f3Stomee { 6734ae67516Stomee StringBuilder buf = new StringBuilder(); 674fb3fb4f3Stomee buf.append(Option.class.getName()); 67552aacb45Stomee buf.append("[name = "); 67652aacb45Stomee buf.append(name); 677fb3fb4f3Stomee buf.append(", value = "); 678fb3fb4f3Stomee buf.append(value); 679fb3fb4f3Stomee buf.append(']'); 680fb3fb4f3Stomee return buf.toString(); 681fb3fb4f3Stomee } 682fb3fb4f3Stomee } 683