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:
# dtrace -v -n dtrace:::BEGIN'{exit(0);}'
dtrace: description 'dtrace:::BEGIN' matched 1 probe
Stability attributes for description dtrace:::BEGIN:
Minimum Probe Description Attributes
Identifier Names: Stable
Data Semantics: Stable
Dependency Class: Common
Minimum Statement Attributes
Identifier Names: Stable
Data Semantics: Stable
Dependency Class: Common
CPU ID FUNCTION:NAME
0 1 :BEGIN
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:
# dtrace -ev -n dtrace:::BEGIN'{trace(curthread->parent);}'
Stability data for description dtrace:::BEGIN:
Minimum probe description attributes
Identifier Names: Evolving
Data Semantics: Evolving
Dependency Class: Common
Minimum probe statement attributes
Identifier Names: Stable
Data Semantics: Private
Dependency Class: Common
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 | Stable/Private/Common |
D user-defined variable | 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.