16.4 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 command with the
-v option to display a report of your program's
stability, as shown in the follow example that uses a program
written on the command line:

You can also choose to combine the -v option
with the -e option, which directs the
dtrace command to compile, but not execute your
D program, so that you can determine program stability without
enabling any probes and executing your program, as shown in the
following stability report:

In this example, notice that in the new program, the D
curthread variable is referenced. This variable
has a Stable name, but Private data semantics: if you look at it,
you are accessing Private implementation details of the kernel.
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 from the
corresponding values for each interface attributes triplet.

Stability attributes are computed for a probe description by
taking the minimum stability attributes of all of the specified
probe description fields, according to the attributes that are
published by the provider. The attributes of the available DTrace
providers are shown in the section corresponding to each provider.
DTrace providers export a stability attributes triplet for each of
the four description fields for all of the probes published by
that provider. Therefore, a provider's name can have a greater
stability than the individual probes that it exports.
For simplicity, most providers use a single set of attributes for
all of the individual module function name values they publish.
Providers also specify attributes for the
args[] array because 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 Unstable/Unstable/Common
stability attributes because the description might end up matching
probes of providers that do not yet exist when used on a future
Oracle Linux release. As such, Oracle does not 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 or macro variables, such as
$1, are treated as unspecified because these
description patterns might expand to match providers or probes to
be released in future versions of DTrace and Oracle Linux. For more
details on pattern matching characters and macro variables, see
Section 2.1, “D Program Structure”and Chapter 9, Scripting.

Stability attributes are computed for most D language statements
by taking the minimum stability and class of the entities in the
statement. The D language entities and their stability attributes
are listed in the following table.

Entity

Attributes

D built-in variable curthread

Stable/Private/Common

D user-defined variable x

Stable/Stable/Common

For example, if you write the following D program statement, the
resulting attributes of the statement are Stable/Private/Common
and the minimum attributes are associated with the
curthread and x operands:

x += curthread->prio;

The stability of an expression is computed by taking the minimum
stability attributes of each of the operands.

Any D variables that you define in your program are automatically
assigned the Stable/Stable/Common attributes. In addition, the D
language grammar and D operators are implicitly assigned these
three attributes. References to kernel symbols by using the back
quote (`) operator are always assigned the
Private/Private/Unknown attributes 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 Stable/Stable/Common
attributes. Types that are defined in the operating system
implementation and provided by other type namespaces are assigned
the Private/Private/Unknown attributes. The D type cast operator
yields an expression with stability attributes that 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 are associated with the C type namespace and are
assigned the Stable/Stable/Common attributes, as the D compiler
automatically assumes you are taking responsibility for these
declarations. It is therefore possible to be misled 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 that
you are including so that you can determine the correct stability
levels.