dtrace_jni.h revision ae94d716ff8759d2dc2de680b5b85a291219a4c1
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * CDDL HEADER START
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * The contents of this file are subject to the terms of the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Common Development and Distribution License (the "License").
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * You may not use this file except in compliance with the License.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * See the License for the specific language governing permissions
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * and limitations under the License.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * When distributing Covered Code, include this CDDL HEADER in each
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * If applicable, add the following below this CDDL HEADER, with the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * fields enclosed by brackets "[]" replaced with your own identifying
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * information: Portions Copyright [yyyy] [name of copyright owner]
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * CDDL HEADER END
e77b06d21580f630e0a7c437495ab283d3672828tomee * Copyright 2008 Sun Microsystems, Inc. All rights reserved.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Use is subject to license terms.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern "C" {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* Java DTrace API native library */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Thread-specific data key used to obtain JNI state specific to either the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * consumer loop (calls dtrace_work()) or the getAggregate() method (calls
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * dtrace_aggregate_print()).
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeetypedef struct dtj_error {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Identifies which function should handle a request dequeued after
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * dtrace_sleep().
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * A request made from Java (by native method call) that is unsafe to process
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * until just after the consumer loop wakes up from dtrace_sleep().
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeetypedef struct dtj_request {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee dtj_request_type_t dtjr_type; /* request handler ID */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee uu_list_t *dtjr_args; /* string args to request handler */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee uu_list_node_t dtjr_node; /* points to next and prev requests */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* Identifier and description of a compiled DTrace program */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeetypedef struct dtj_program {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee const char *dtjp_name; /* string or filename for err msg */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee dtrace_prog_t *dtjp_program; /* libdtrace program handle */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee boolean_t dtjp_enabled; /* dtrace_program_exec() flag */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee uu_list_node_t dtjp_node; /* points to next and prev programs */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * An entry used to maintain the association between the value of an aggregating
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * action (such as count()) and the aggregation to which the value belongs until
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * all the data associated with a single tuple is available to the callback
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeetypedef struct dtj_aggval {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee uu_list_node_t dtja_node; /* points to next and prev aggvals */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Per-consumer state, including the libdtrace consumer handle, is valid across
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * multiple threads. One consumer entry is added to a global table per
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * dtrace_open().
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeetypedef struct dtj_consumer {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee /* Consumer state */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee dtrace_hdl_t *dtjc_dtp; /* libdtrace consumer handle */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Count of processes that have ended. The consumer is stopped when
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * this count equals the number of outstanding target processes and
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * grabbed processes (see the Java Consumer createProcess() and
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * grabProcess() methods).
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Bit-field passed to dtrace_program_strcompile() and
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * dtrace_program_fcompile() containing compile flags. The flags are
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * set from Java by the setOption() Consumer method (just like the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * runtime options handled by dtrace_setopt(), except that they must be
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * set before program compilation to have any effect).
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee boolean_t dtjc_flow; /* current value of the flowindent option */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee dtj_consumer_state_t dtjc_state; /* execution state */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee boolean_t dtjc_interrupt; /* flag that stops consumer */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee /* Pending requests */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee /* Cached for optimization and for use across functions */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Nanosecond timestamp cached in the consumer loop just before
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * dtrace_work(). The timestamp is applied to each Java PrintaRecord
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * generated in that iteration of the consumer loop. A value of zero
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * indicates that we are not in the consumer loop, but that the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * callback was triggered instead by the Consumer getAggregate() method
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * (from dtrace_aggregate_print()).
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * The aggregation ID is used to optimize aggregation inclusion by
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * testing for inclusion only when the aggregation has changed.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * The expected tuple member count is used to determine whether or not
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * the aggregation tuple values are completely specified in the printa()
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * format string.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee int dtjc_probedata_rec_i; /* probe data record index */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * The current DTrace action may apply across multiple libdtrace probe
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * data records.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee /* Placeholder used when listing probes */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee /* Function used by statement iterator when listing probes */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * A view of a dtj_consumer_t that lasts only as long as a single native method
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * call. This view attaches state needed for interaction with Java and specific
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * to the JNI.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeetypedef struct dtj_java_consumer {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee /* Per-consumer state in global consumer table */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee jobject dtjj_caller; /* Java Consumer to call back with probe data */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Java Object references used across function boundaries, valid only
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * within the current native method call.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee jobject dtjj_probedata; /* instance of class ProbeData */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * StringBuffer used to concatenate buffered printa() output associated
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * with the current tuple.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee jobject dtjj_aggregate; /* instance of class Aggregate */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * AggregationValue instances cached until we receive the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * DTRACE_BUFDATA_AGGLAST flag indicating the last callback associated
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * with the current tuple.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee /* AggregateSpec used by get_aggregate() */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee jobject dtjj_probelist; /* java.util.List returned by listProbes() */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Exception temporarily cleared by callback handlers who cannot return
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * a signal to abort the consumer. At a safe point when the consumer
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * loop gets control back from libdtrace, the exception is rethrown.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Cache of jclass, jmethodID, and jfieldID values, usable across multiple
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * native method calls and multiple threads. Caching all of them up front
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * rather than as-needed guarantees early detection of incorrect class, method,
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * or field definitions, and eliminates the need for test cases to cover
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * seldom-used definitions.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Suffix conventions:
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * jc java class
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * jm java method
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * jsm java static method
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * jf java field
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * jsf java static field
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* LocalConsumer */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* DTraceException */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* InterfaceAttributes */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* ProbeDescription */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* ProbeInfo */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* Program */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* Program.File */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* ProgramInfo */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* ProbeData */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* ProcessState */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* Aggregate */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* AggregateSpec */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* AggregationRecord */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* SumValue */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* CountValue */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* AvgValue */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* MinValue */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* MaxValue */
e77b06d21580f630e0a7c437495ab283d3672828tomee/* StddevValue */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* KernelStackRecord */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* UserStackRecord */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* Distribution */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* LogDistribution */
ae94d716ff8759d2dc2de680b5b85a291219a4c1Richard Lowe/* LogLinearDistribution */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* LinearDistribution */
127bbe13a6d36580af6a8ded154f1201a6250772tomee/* KernelSymbolRecord */
127bbe13a6d36580af6a8ded154f1201a6250772tomee/* UserSymbolRecord */
127bbe13a6d36580af6a8ded154f1201a6250772tomee/* ScalarRecord */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Populates the java class references and associated method and field IDs
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * declared in this file (above).
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Throws NoClassDefFoundError, NoSuchMethodError, or NoSuchFieldError if any
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * dtj_table_entry_t in dtj_jnitab.c is incorrect.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Functions that create a structure return NULL if out of memory. A Java
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * OutOfMemoryError is pending in that case.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern dtj_request_t *dtj_request_create(JNIEnv *, dtj_request_type_t, ...);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern dtj_program_t *dtj_program_create(JNIEnv *, dtj_program_type_t,
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee const char *);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern dtj_aggval_t *dtj_aggval_create(JNIEnv *, jobject, const char *,
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * uu_list_t element destructors' signatures match uuwrap_value_destroy_f
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern void dtj_request_destroy(void *, void *); /* expects NULL user arg */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern void dtj_program_destroy(void *, void *); /* expects NULL user arg */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern void dtj_aggval_destroy(void *, void *); /* expects JNIEnv * user arg */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* Allocates and frees per-consumer state kept in the global consumer table */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* Sets callback handlers before calling dtrace_go() */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern dtj_status_t dtj_set_callback_handlers(dtj_java_consumer_t *);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Initializes Java Object references cached across multiple functions called
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * within the consumer loop. Deletes the references after exiting the consumer
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * loop. It is only necessary to initialize and finalize a dtj_java_consumer_t
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * if the native method call will enter the consumer loop.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern dtj_status_t dtj_java_consumer_init(JNIEnv *, dtj_java_consumer_t *);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern void dtj_java_consumer_fini(JNIEnv *, dtj_java_consumer_t *);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Throws a DTraceException with a message constructed from the given format
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * string and variable arg list.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern void dtj_throw_dtrace_exception(dtj_java_consumer_t *,
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee const char *, ...);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* Returns NULL if pending Java Exception or OutOfMemoryError */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern jobject dtj_new_probedesc(dtj_java_consumer_t *,
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern jobject dtj_new_probeinfo(dtj_java_consumer_t *,
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern jobject dtj_new_attribute(dtj_java_consumer_t *,
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * Returns NULL if the given fault is unrecognized, otherwise returns the name
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * of the fault, guaranteed not to change across multiple versions of this API
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * even if the integer value changes in libdtrace.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern const char *dtj_get_fault_name(int);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* Gets the libdtrace error number and message */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern dtj_status_t dtj_get_dtrace_error(dtj_java_consumer_t *, dtj_error_t *);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee/* Stops the DTrace consumer */
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * The Consumer getAggregate() method runs in the caller's current thread
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * separate from the consumer loop.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern jobject dtj_get_aggregate(dtj_java_consumer_t *);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * A blocking call that runs the consumer loop. If this function returns an
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * error status, it is necessary to call stop() in order to dtrace_stop() the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee * consumer in libdtrace (it is safe to call stop() in either case).
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeextern dtj_status_t dtj_consume(dtj_java_consumer_t *);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee#endif /* _DTRACE_JNI_H */