PAPI_attach(3)

1PAPI_attach(3)                       PAPI                       PAPI_attach(3)
2
3
4

NAME

6       PAPI_attach  - attach PAPI event set to the specified thread id
7       PAPI_detach  - detach PAPI event set from previously specified thread id and restore to executing thread
8
9

SYNOPSIS

11       C Interface
12       #include <papi.h>
13       int PAPI_attach(int EventSet, unsigned long tid);
14       int PAPI_detach(int EventSet);
15       Fortran Interface
16       <none>
17
18

DESCRIPTION

20       PAPI_attach()  and  PAPI_detach()  are  wrapper  functions  that access
21       PAPI_set_opt() (3) to allow PAPI to monitor  performance  counts  on  a
22       thread  other  than  the  one  currently  executing.  This is sometimes
23       referred to as third  party  monitoring.   PAPI_attach()  connects  the
24       specified  EventSet  to  the specifed thread; PAPI_detach() breaks that
25       connection and restores the EventSet to the original executing thread.
26
27

ARGUMENTS

29       EventSet --  an integer handle for a  PAPI  Event  Set  as  created  by
30       PAPI_create_eventset(3)
31
32       tid  -- a thread id as obtained from, for example, PAPI_list_threads(3)
33       or PAPI_thread_id(3).
34
35

RETURN VALUES

37       On success, these functions return PAPI_OK.  On error, a negative error
38       code is returned.
39
40

ERRORS

42       PAPI_ESBSTR
43              This feature is unsupported on this substrate.
44
45       PAPI_EINVAL
46              One or more of the arguments is invalid.
47
48       PAPI_ENOEVST
49              The event set specified does not exist.
50
51       PAPI_EISRUN
52              The event set is currently counting events.
53
54
55

EXAMPLES

57       int EventSet = PAPI_NULL;
58       unsigned long pid;
59
60       pid = fork();
61       if (pid <= 0)
62         exit(1);
63
64       if (PAPI_create_eventset(&EventSet) != PAPI_OK)
65         exit(1);
66
67       /* Add Total Instructions Executed to our EventSet */
68
69       if (PAPI_add_event(EventSet, PAPI_TOT_INS) != PAPI_OK)
70         exit(1);
71
72       /* Attach this EventSet to the forked process */
73
74       if (PAPI_attach(EventSet, pid) != PAPI_OK)
75         exit(1);
76
77
78
79

BUGS

81       There are no known bugs in these functions.
82
83