Stability Computations and Reports

The D compiler performs stability computations for each of the probe descriptions and
action statements in your D programs. You can use the dtrace -v
option to display a report of your program's stability. The following example uses
a program written on the command line:

You may also wish to combine the dtrace -v option with the -e
option, which tells dtrace to compile but not execute your D program, so
that you can determine program stability without having to enable any probes and
execute your program. Here is another example stability report:

Notice that in our new program, we have referenced the D variable
curthread, which has a Stable name, but Private data semantics (that is, if
you look at it, you are accessing Private implementation details of the kernel),
and this status is now reflected in the program's stability report. Stability attributes
in the program report are computed by selecting the minimum stability level and
class out of the corresponding values for each interface attributes triplet.

Stability attributes are computed for a probe description by taking the minimum stability
attributes of all specified probe description fields according to the attributes published by
the provider. The attributes of the available DTrace providers are shown in the
chapter corresponding to each provider. DTrace providers export a stability attributes triplet for each
of the four description fields for all probes published by that provider. Therefore,
a provider's name may have a greater stability than the individual probes it
exports. For example, the probe description:

fbt:::

indicating that DTrace should trace entry and return from all kernel functions, has
greater stability than the probe description:

fbt:foo:bar:entry

which names a specific internal function bar in the kernel module foo. For
simplicity, most providers use a single set of attributes for all of the
individual module function name values that they publish. Providers also specify attributes for the args[]
array, as the stability of any probe arguments varies by provider.

If the provider field is not specified in a probe description, then the
description is assigned the stability attributes Unstable/Unstable/Common because the description might end up
matching probes of providers that do not yet exist when used on a
future Oracle Solaris version. As such, Oracle is not able to provide guarantees
about the future stability and behavior of this program. You should always explicitly
specify the provider when writing your D program clauses. In addition, any probe
description fields that contain pattern matching characters (see D Program Structure) or macro variables such as
$1 (see Chapter 9, Scripting) are treated as if they are unspecified because these
description patterns might expand to match providers or probes released in future versions of
DTrace and the Oracle Solaris OS.

Stability attributes are computed for most D language statements by taking the minimum
stability and class of the entities in the statement. For example, the following
D language entities have the following attributes:

Entity

Attributes

D built-in variable curthread

Stable/Private/Common

D user-defined variable
x

Stable/Stable/Common

If you write the following D program statement:

x += curthread->t_pri;

then the resulting attributes of the statement are Stable/Private/Common, the minimum attributes associated
with the operands curthread and x. The stability of an expression is
computed by taking the minimum stability attributes of each of the operands.

Any D variables you define in your program are automatically assigned the attributes
Stable/Stable/Common. In addition, the D language grammar and D operators are implicitly assigned
the attributes Stable/Stable/Common. References to kernel symbols using the backquote (`) operator are always
assigned the attributes Private/Private/Unknown because they reflect implementation artifacts. Types that you define
in your D program source code, specifically those that are associated with the
C and D type namespace, are assigned the attributes Stable/Stable/Common. Types that are
defined in the operating system implementation and provided by other type namespaces are assigned
the attributes Private/Private/Unknown. The D type cast operator yields an expression whose stability
attributes are the minimum of the input expression's attributes and the attributes of
the cast output type.

If you use the C preprocessor to include C system header files,
these types will be associated with the C type namespace and will be
assigned the attributes Stable/Stable/Common as the D compiler has no choice but to
assume that you are taking responsibility for these declarations. It is therefore possible to
mislead yourself about your program's stability if you use the C preprocessor to
include a header file containing implementation artifacts. You should always consult the documentation
corresponding to the header files you are including in order to determine the
correct stability levels.