cpc_enable(3cpc)

1cpc_enable(3CPC)  CPU Performance Counters Library Functions  cpc_enable(3CPC)
2
3
4

NAME

6       cpc_enable, cpc_disable - enable and disable performance counters
7

SYNOPSIS

9       cc [ flag... ] file... -lcpc [ library... ]
10       #include <libcpc.h>
11
12       int cpc_enable(cpc_t *cpc);
13
14
15       int cpc_disable(cpc_t *cpc);
16
17

DESCRIPTION

19       In certain applications, it can be useful to explicitly enable and dis‐
20       able performance counters at different times so that the performance of
21       a  critical  algorithm  can  be examined. The cpc_enable() and cpc_dis‐
22       able() functions can be used to  enable  and  disable  the  performance
23       counters  without  otherwise  disturbing the invoking LWP's performance
24       hardware configuration.
25

RETURN VALUES

27       Upon successful completion, cpc_enable() and  cpc_disable()  return  0.
28       Otherwise, they return -1 and set errno to indicate the error.
29

ERRORS

31       These functions will fail if:
32
33       EAGAIN    The  associated  performance counter context has been invali‐
34                 dated by another process.
35
36
37       EINVAL    No performance counter context has been created for the call‐
38                 ing LWP.
39
40

EXAMPLES

42       Example  1  Use  cpc_enable  and cpc_disable to minimize code needed by
43       application.
44
45
46       In the following example, the cpc_enable() and cpc_disable()  functions
47       are  used  to minimize the amount of code that needs to be added to the
48       application. The cputrack(1) command can be used  in  conjunction  with
49       these  functions  to provide event programming, sampling, and reporting
50       facilities.
51
52
53
54       If the application is instrumented in this way and then started by cpu‐
55       track  with the nouser flag set in the event specification, counting of
56       user events will only be enabled around the critical  code  section  of
57       interest. If the program is run normally, no harm will ensue.
58
59
60         int
61         main(int argc, char *argv[])
62         {
63            cpc_t *cpc = cpc_open(CPC_VER_CURRENT);
64             /* ... application code ... */
65
66            if (cpc != NULL)
67                    (void) cpc_enable(cpc);
68
69             /* ==> Code to be measured goes here <== */
70
71            if (cpc != NULL)
72                    (void) cpc_disable(cpc);
73
74             /* ... other application code */
75         }
76
77

ATTRIBUTES

79       See attributes(5) for descriptions of the following attributes:
80
81
82
83
84       ┌─────────────────────────────┬─────────────────────────────┐
85       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
86       ├─────────────────────────────┼─────────────────────────────┤
87       │Interface Stability          │Evolving                     │
88       ├─────────────────────────────┼─────────────────────────────┤
89       │MT-Level                     │Safe                         │
90       └─────────────────────────────┴─────────────────────────────┘
91