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:

# 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 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.