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:

# dtrace -v -n dtrace:::BEGIN'{exit(0);}'
dtrace: description 'dtrace:::BEGIN' matched 1 probe
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:   Stable
                Dependency Class: Common
CPU     ID                    FUNCTION:NAME
  0      1                           :BEGIN

You can also combine the dtrace -v option with the -e option, which only compiles 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:

# dtrace -ev -n dtrace:::BEGIN'{trace(curthread->t_procp);}'
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
#

This example references the D variable curthread, which has a Stable name, but Private data semantics, which is 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:::

This example probe indicates that DTrace should trace entry and return from all kernel functions as this has greater stability than the probe description:

fbt:foo:bar:entry

This probe 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 must always explicitly specify the provider when writing the D program clauses. In addition, any probe description fields that contain pattern matching characters 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. For more information about pattern matching characters, see D Program Structure or macro variables such as $1, see Scripting in DTrace.

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:

• D built-in variable curthread – Stable/Private/Common

• D user-defined variable x – Stable/Stable/Common

For example, write the following D program statement:

x += curthread->t_pri;

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. Therefore, you might be misled about the 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.