Stability

Sun often provides developers with early access to new technologies as well as observability tools that allow users to peer into the internal implementation details of user and kernel software. Unfortunately, new technologies and internal implementation details are both prone to changes as interfaces and implementations evolve and mature when software is upgraded or patched. Sun documents application and interface stability levels using a set of labels described in the [{{attributes}}(5)|http://docs.sun.com/doc/819-2252/attributes-5?a=view] man page to help set user expectations for what kinds of changes might occur in different kinds of future releases.\\
\\No one stability attribute appropriately describes the arbitrary set of entities and services that can be accessed from a D program. DTrace and the D compiler therefore include features to dynamically compute and describe the stability levels of D programs you create. This chapter discusses the DTrace features for determining program stability to help you design stable D programs. You can use the DTrace stability features to inform you of the stability attributes of your D programs, or to produce compile-time errors when your program has undesirable interface dependencies.

[Top|#top]
h2. {anchor:CHP-STAB-1} Stability Levels
DTrace provides two types of stability attributes for entities such as built-in variables, functions, and probes: a _stability level_ and an architectural _dependency class_. The DTrace stability level assists you in making risk assessments when developing scripts and tools based on DTrace by indicating how likely an interface or DTrace entity is to change in a future release or patch. The DTrace dependency class tells you whether an interface is common to all Solaris platforms and processors, or whether the interface is associated with a particular architecture such as SPARC processors only. The two types of attributes used to describe interfaces can vary independently.\\
\\The stability values used by DTrace appear in the following list in order from lowest to highest stability. The more stable interfaces can be used by all D programs and layered applications because Sun will endeavor to ensure that these continue to work in future minor releases. Applications that depend only on Stable interfaces should reliably continue to function correctly on future minor releases and will not be broken by interim patches. The less stable interfaces allow experimentation, prototyping, tuning, and debugging on your current system, but should be used with the understanding that they might change incompatibly or even be dropped or replaced with alternatives in future minor releases.\\
\\The DTrace stability values also help you understand the stability of the software entities you are observing, in addition to the stability of the DTrace interfaces themselves. Therefore, DTrace stability values also tell you how likely your D programs and layered tools are to require corresponding changes when you upgrade or change the software stack you are observing.
{section}
{column:width=15%}
Internal
{column}
{column:width=85%}
The interface is private to DTrace and represents an implementation detail of DTrace. Internal interfaces might change in minor or micro releases.
{column}
{section}
{section}
{column:width=15%}
Private
{column}
{column:width=85%}
The interface is private to Sun and represents an interface developed for use by other Sun products that is not yet publicly documented for use by customers and ISVs. Private interfaces might change in minor or micro releases.
{column}
{section}
{section}
{column:width=15%}
Obsolete
{column}
{column:width=85%}
The interface is supported in the current release but is scheduled to be removed, most likely in a future minor release. When support of an interface is to be discontinued, Sun will attempt to provide notification before discontinuing the interface. The D compiler might produce warning messages if you attempt to use an Obsolete interface.
{column}
{section}
{section}
{column:width=15%}
External
{column}
{column:width=85%}
The interface is controlled by an entity other than Sun. At Sun's discretion, Sun can deliver updated and possibly incompatible versions of such interfaces as part of any release, subject to their availability from the controlling entity. Sun makes no claims regarding either source or binary compatibility for External interfaces between any two releases. Applications based on these interfaces might not work in future releases, including patches that contain External interfaces.
{column}
{section}
{section}
{column:width=15%}
Unstable
{column}
{column:width=85%}
The interface is provided to give developers early access to new or rapidly changing technology or to an implementation artifact that is essential for observing or debugging system behavior for which a more stable solution is anticipated in the future. Sun makes no claims about either source or binary compatibility for Unstable interfaces from one minor release to another.
{column}
{section}
{section}
{column:width=15%}
Evolving
{column}
{column:width=85%}
The interface might eventually become Standard or Stable but is still in transition. Sun will make reasonable efforts to ensure compatibility with previous releases as it evolves. When non-upward compatible changes become necessary, they will occur in minor and major releases. These changes will be avoided in micro releases whenever possible. If such a change is necessary, it will be documented in the release notes for the affected release, and when feasible, Sun will provide migration aids for binary compatibility and continued D program development.
{column}
{section}
{section}
{column:width=15%}
Stable
{column}
{column:width=85%}
The interface is a mature interface under Sun's control. Sun will try to avoid non-upward-compatible changes to these interfaces, especially in minor or micro releases. If support of a Stable interface must be discontinued, Sun will attempt to provide notification and the stability level changes to Obsolete.
{column}
{section}
{section}
{column:width=15%}
Standard
{column}
{column:width=85%}
The interface complies with an industry standard. The corresponding documentation for the interface will describe the standard to which the interface conforms. Standards are typically controlled by a standards development organization, and changes can be made to the interface in accordance with approved changes to the standard. This stability level can also apply to interfaces that have been adopted(without a formal standard by an industry convention. Support is provided for only the specified versions of a standard; support for later versions is not guaranteed. If the standards development organization approves a non-upward-compatible change to a Standard interface that Sun decides to support, Sun will announce a compatibility and migration strategy.
{column}
{section}

[Top|#top]
h2. {anchor:CHP-STAB-2} Dependency Classes
Since Solaris and DTrace support a variety of operating platforms and processors, DTrace also labels interfaces with a _dependency class_ that tells you whether an interface is common to all Solaris platforms and processors, or whether the interface is associated with a particular system architecture. The dependency class is orthogonal to the stability levels described earlier. For example, a DTrace interface can be Stable but only supported on SPARC microprocessors, or it can be Unstable but common to all Solaris systems. The DTrace dependency classes are described in the following list in order from least common (that is, most specific to a particular architecture) to most common (that is, common to all architectures).
{section}
{column:width=15%}
Unknown
{column}
{column:width=85%}
The interface has an unknown set of architectural dependencies. DTrace does not necessarily know the architectural dependencies of all entities, such as data types defined in the operating system implementation. The Unknown label is typically applied to interfaces of very low stability for which dependencies cannot be computed. The interface might not be available when using DTrace on _any_ architecture other than the one you are currently using.
{column}
{section}
{section}
{column:width=15%}
CPU
{column}
{column:width=85%}
The interface is specific to the CPU model of the current system. You can use the [{{psrinfo}}(1M)|http://docs.sun.com/doc/819-2240/psrinfo-1m?a=view] utility's \-v option to display the current CPU model and implementation names. Interfaces with CPU model dependencies might not be available on other CPU implementations, even if those CPUs export the same instruction set architecture (ISA). For example, a CPU-dependent interface on an UltraSPARC-III+ microprocessor might not be available on an UltraSPARC-II microprocessor, even though both processors support the SPARC instruction set.
{column}
{section}
{section}
{column:width=15%}
Platform
{column}
{column:width=85%}
The interface is specific to the hardware platform of the current system. A platform typically associates a set of system components and architectural characteristics such as a set of supported CPU models with a system name such as {{SUNW,Ultra-Enterprise-10000}}. You can display the current platform name using the [{{uname}}(1)|http://docs.sun.com/doc/819-2239/uname-1?a=view] \-i option. The interface might not be available on other hardware platforms.
{column}
{section}
{section}
{column:width=15%}
Group
{column}
{column:width=85%}
The interface is specific to the hardware platform group of the current system. A platform group typically associates a set of platforms with related characteristics together under a single name, such as {{sun4u}}. You can display the current platform group name using the [{{uname}}(1)|http://docs.sun.com/doc/819-2239/uname-1?a=view] \-m option. The interface is available on other platforms in the platform group, but might not be available on hardware platforms that are not members of the group.
{column}
{section}
{section}
{column:width=15%}
ISA
{column}
{column:width=85%}
The interface is specific to the instruction set architecture (ISA) supported by the microprocessors on this system. The ISA describes a specification for software that can be executed on the microprocessor, including details such as assembly language instructions and registers. You can display the native instruction sets supported by the system using the [{{isainfo}}(1)|http://docs.sun.com/doc/819-2239/isainfo-1?a=view] utility. The interface might not be supported on systems that do not export any of the same instruction sets. For example, an ISA-dependent interface on a Solaris SPARC system might not be supported on a Solaris x86 system.
{column}
{section}
{section}
{column:width=15%}
Common
{column}
{column:width=85%}
The interface is common to all Solaris systems regardless of the underlying hardware. DTrace programs and layered applications that depend only on Common interfaces can be executed and deployed on other Solaris systems with the same Solaris and DTrace revisions. The majority of DTrace interfaces are Common, so you can use them wherever you use Solaris.
{column}
{section}

[Top|#top]
h2. {anchor:CHP-STAB-3} Interface Attributes
DTrace describes interfaces using a triplet of attributes consisting of two stability levels and a dependency class. By convention, the interface attributes are written in the following order, separated by slashes:
{noformat}
name-stability / data-stability / dependency-class
{noformat}
The _name stability_ of an interface describes the stability level associated with its name as it appears in your D program or on the [{{dtrace}}(1M)|http://docs.sun.com/doc/819-2240/dtrace-1m?a=view] command-line. For example, the {{execname}} D variable is a Stable name: Sun guarantees that this identifier will continue to be supported in your D programs according to the rules described for Stable interfaces above.\\
\\The _data stability_ of an interface is distinct from the stability associated with the interface name. This stability level describes Sun's commitment to maintaining the data formats used by the interface and any associated data semantics. For example, the {{pid}} D variable is a Stable interface: process IDs are a Stable concept in Solaris, and Sun guarantees that the {{pid}} variable will be of type {{pid_t}} with the semantic that it is set to the process ID corresponding to the thread that fired a given probe in accordance with the rules for Stable interfaces.\\
\\The _dependency class_ of an interface is distinct from its name and data stability, and describes whether the interface is specific to the current operating platform or microprocessor.\\
\\DTrace and the D compiler track the stability attributes for all of the DTrace interface entities, including providers, probe descriptions, D variables, D functions, types, and program statements themselves, as we'll see shortly. Notice that all three values can vary independently. For example, the {{curthread}} D variable has Stable/Private/Common attributes: the variable name is Stable and is Common to all Solaris operating platforms, but this variable provides access to a Private data format that is an artifact of the Solaris kernel implementation. Most D variables are provided with Stable/Stable/Common attributes, as are the variables you define.

[Top|#top]
h2. {anchor:CHP-STAB-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}} \-v option to display a report of your program's stability. The following example uses a program written on the command line:
{noformat}
# 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
{noformat}
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:
{noformat}
# 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
#
{noformat}
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:
{noformat}
fbt:::
{noformat}
indicating that DTrace should trace entry and return from all kernel functions, has greater stability than the probe description:
{noformat}
fbt:foo:bar:entry

|D built-in variable {{curthread}}|Stable/Private/Common|
|D user-defined variable {{x}}|Stable/Stable/Common|
If you write the following D program statement:
{noformat}
x += curthread->t_pri;
{noformat}
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.

[Top|#top]
h2. {anchor:CHP-STAB-5} Stability Enforcement
When developing a DTrace script or layered tool, you may wish to identify the specific source of stability issues or ensure that your program has a desired set of stability attributes. You can use the {{dtrace -x amin=_attributes_}} option to force the D compiler to produce an error when any attributes computation results in a triplet of attributes less than the minimum values you specify on the command-line. The following example demonstrates the use of \-x amin using a snippet of D program source. Notice that attributes are specified using three labels delimited by {{/}} in the usual order.
{noformat}
# dtrace -x amin=Evolving/Evolving/Common \
-ev -n dtrace:::BEGIN'{trace(curthread->t_procp);}'
dtrace: invalid probe specifier dtrace:::BEGIN{trace(curthread->t_procp);}: \
in action list: attributes for scalar curthread (Stable/Private/Common) \
are less than predefined minimum
#
{noformat}
{excerpt:hidden=true}Converted by tech dogg's sgml2wiki on Tue 20 Nov 2007 at 9:28:01 PM{excerpt}