ATL Attributes: perf_counter

Adds Perfmon counter support to a class member variable

Syntax

[
    define_attribute = "perf_counter",
    argument_list = {
        "namestring",
        "helpstring",
        "name_res",
        "help_res",
        "countertype",
        "defscale",
        "default_counter",
        "detail",
        "max_counter_size",
        "countertype_string"
    },
    argument_type ("namestring") = eANSIStringValue,
    argument_type ("helpstring") = eANSIStringValue,
    argument_type ("name_res") = eIntegerValue,
    argument_type ("help_res") = eIntegerValue,
    argument_type ("countertype") = eIntegerValue,
    argument_type ("defscale") = eIntegerValue,
    argument_type ("default_counter") = eBooleanValue,
    argument_type ("detail") = eIntegerValue,
    argument_type ("max_counter_size") = eIntegerValue,
    default_value ("namestring") = "!!",
    default_value ("helpstring") = "!!",
    default_value ("name_res") = "!!",
    default_value ("help_res") = "!!",
    default_value ("countertype") = "!!",
    default_value ("defscale") = "0",
    default_value ("default_counter") = "false",
    default_value ("detail") = "PERF_DETAIL_NOVICE",
    default_value ("max_counter_size") = "0",
    default_value ("countertype_string") = "!!",
    help_string = "Adds Perfmon counter support to a class member variable",
    usage = eMemberUsage,
    group = eHPS,
    repeatable = true,
    shipping = true
];

It is an error (ATL2103) not to have at least one valid use of the perf_object attribute before any use of the perf_counter attribute.

The name_res, help_res, namestring and helpstring arguments are expected in either of the following combinations:

• a name_res and help_res, and neither a namestring nor helpstring
• a namestring and helpstring, and neither a name_res nor help_res

Anything else is an error (ATL2102).

Exactly one of the countertype and countertype_string arguments must be supplied. It is an error (ATL2104) to give neither or to give both.

The case-insensitive countertype_string argument may be base, bulk_count, counter, elapsed, fraction, histogram, precision, queuelen, rate, rawcount, text, timer or value. Anything else is an error (ATL2105).

If the default_counter argument evaluates to true, then it is an error (ATL2100) if a default counter already has been set for the class to which the perf_object attribute was most recently applied.

Documentation Errors

The product documentation lists the countertype argument twice. The first position is correct. Ignore the second.

Repeatability

The product documentation says that this attribute is not repeatable. The value in applying perf_counter multiple times to the one data member may be dubious, but the exercise is explicitly permitted by the formal syntax definition and thence by the compiler. For example, in

#define     _ATL_ATTRIBUTES
#include    <atlbase.h>
#include    <atlperf.h>

[
    perf_object (namestring = "TestObject", helpstring "test object")
]
class Test
{
    [
        perf_counter (
            namestring = "Counter1",
            helpstring "counter as rate",
            countertype_string = "rate"
        ),
        perf_counter (
            namestring = "Counter2",
            helpstring "counter as value",
            countertype_string = "value"
        )
    ]
    int m_x;
};

the one data member is defined as two counters, each with their own ID.

Relations with perf_object

The product documentation says that when perf_counter is applied to a data member of some class, then this class must be defined using the perf_object attribute. This is true if injected code is wanted from using perf_counter. It should perhaps be clarified however that a perf_counter applied in defiance of the documentation’s stated requirement will not certainly be rejected by ATLPROV with a warning or error (such as ATL2103). Provided there is at least one valid use of perf_object beforehand, even for a different class, a spurious perf_counter will be checked for syntax but will be ignored when injecting code.