[lttv.git] / tags / lttv-0.10.0-pre15-12082008 / doc / developer / developer_guide / html / x33.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>The hooks</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
TITLE="Linux Trace Toolkit Viewer Developer Guide"
HREF="index.html"><LINK
REL="UP"
TITLE="Linux Trace Toolkit Viewer Text Module Tutorial"
HREF="c18.html"><LINK
REL="PREVIOUS"
TITLE="A typical module"
HREF="x23.html"><LINK
REL="NEXT"
TITLE="How to use the Linux Trace Toolkit Viewer's Reading Context"
HREF="c40.html"></HEAD
><BODY
CLASS="sect1"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>Linux Trace Toolkit Viewer Developer Guide</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="x23.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>Chapter 1. Linux Trace Toolkit Viewer Text Module Tutorial</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="c40.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="AEN33"
>1.3. The hooks</A
></H1
><P
>&#13;The before and after trace hooks only exists to be able to generate a report at
the end of a trace computation. The effective computation is done by the event
hooks.
</P
><P
>&#13;These hooks does particular computation on data arriving as argument, a
call_data. The type of the call_data, when a hook is called during the trace
read, is a traceset context. It contains all the necessary information about the
read in progress. This is the base class from which inherits trace set
state, and trace set/trace/tracefile state is the base classe of trace
set/trace/tracefile statistics. All these types can be casted to another without
problem (a TracesetState, for example, can be casted to a TracesetContext, but
it's not true for the casting between a TraceContext and a TracesetContext, see
the chapter "How to use the trace reading context" for details). They offer the
input data and they give a container (the attributes of the trace set/trace/tracefile
statistics) to write the output of this hook.
</P
><P
>&#13;The idea behind writing in the attributes container is to provide an extensible
way of storing any type of information. For example, a specific module that adds
statistics to a trace can store them there, and the statistic printout will
automatically include the results produced by the specific module.
</P
><P
>&#13;Output data does not necessarily need to be stored in such a global container
though. If we think of data of which we need to keed track during the execution,
an event counter for example, we should create our own data structure that
contains this counter, and pass the address of the allocated structure as the
hook_data parameter of the hook list creation function. That way, the hook will
be called with its hook_data as first parameter, which it can read and write. We
can think of this structure as the data related to the function that persists
between each call to the hook. You must make sure that you cast the hook_data to
the type of the structure before you use it in the hook function.
</P
><P
>&#13;The detail about how to access the different fields of the reading context (the
hook's call_data) will be discussed in the chapter  "How to use the trace
reading context".
</P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="x23.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="c40.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>A typical module</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="c18.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>How to use the Linux Trace Toolkit Viewer's Reading Context</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
Commit	Line	Data
5750899b	1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
	2	<HTML
	3	><HEAD
	4	><TITLE
	5	>The hooks</TITLE
	6	><META
	7	NAME="GENERATOR"
	8	CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
	9	REL="HOME"
	10	TITLE="Linux Trace Toolkit Viewer Developer Guide"
	11	HREF="index.html"><LINK
	12	REL="UP"
	13	TITLE="Linux Trace Toolkit Viewer Text Module Tutorial"
	14	HREF="c18.html"><LINK
	15	REL="PREVIOUS"
	16	TITLE="A typical module"
	17	HREF="x23.html"><LINK
	18	REL="NEXT"
	19	TITLE="How to use the Linux Trace Toolkit Viewer's Reading Context"
	20	HREF="c40.html"></HEAD
	21	><BODY
	22	CLASS="sect1"
	23	BGCOLOR="#FFFFFF"
	24	TEXT="#000000"
	25	LINK="#0000FF"
	26	VLINK="#840084"
	27	ALINK="#0000FF"
	28	><DIV
	29	CLASS="NAVHEADER"
	30	><TABLE
	31	SUMMARY="Header navigation table"
	32	WIDTH="100%"
	33	BORDER="0"
	34	CELLPADDING="0"
	35	CELLSPACING="0"
	36	><TR
	37	><TH
	38	COLSPAN="3"
	39	ALIGN="center"
	40	>Linux Trace Toolkit Viewer Developer Guide</TH
	41	></TR
	42	><TR
	43	><TD
	44	WIDTH="10%"
	45	ALIGN="left"
	46	VALIGN="bottom"
	47	><A
	48	HREF="x23.html"
	49	ACCESSKEY="P"
	50	>Prev</A
	51	></TD
	52	><TD
	53	WIDTH="80%"
	54	ALIGN="center"
	55	VALIGN="bottom"
	56	>Chapter 1. Linux Trace Toolkit Viewer Text Module Tutorial</TD
	57	><TD
	58	WIDTH="10%"
	59	ALIGN="right"
	60	VALIGN="bottom"
	61	><A
	62	HREF="c40.html"
	63	ACCESSKEY="N"
	64	>Next</A
65	></TD
66	></TR
67	></TABLE
68	><HR
69	ALIGN="LEFT"
70	WIDTH="100%"></DIV
71	><DIV
72	CLASS="sect1"
73	><H1
74	CLASS="sect1"
75	><A
76	NAME="AEN33"
77	>1.3. The hooks</A
78	></H1
79	><P
80	> The before and after trace hooks only exists to be able to generate a report at
81	the end of a trace computation. The effective computation is done by the event
82	hooks.
83	</P
84	><P
85	> These hooks does particular computation on data arriving as argument, a
86	call_data. The type of the call_data, when a hook is called during the trace
87	read, is a traceset context. It contains all the necessary information about the
88	read in progress. This is the base class from which inherits trace set
89	state, and trace set/trace/tracefile state is the base classe of trace
90	set/trace/tracefile statistics. All these types can be casted to another without
91	problem (a TracesetState, for example, can be casted to a TracesetContext, but
92	it's not true for the casting between a TraceContext and a TracesetContext, see
93	the chapter "How to use the trace reading context" for details). They offer the
94	input data and they give a container (the attributes of the trace set/trace/tracefile
95	statistics) to write the output of this hook.
96	</P
97	><P
98	> The idea behind writing in the attributes container is to provide an extensible
99	way of storing any type of information. For example, a specific module that adds
100	statistics to a trace can store them there, and the statistic printout will
101	automatically include the results produced by the specific module.
102	</P
103	><P
104	> Output data does not necessarily need to be stored in such a global container
105	though. If we think of data of which we need to keed track during the execution,
106	an event counter for example, we should create our own data structure that
107	contains this counter, and pass the address of the allocated structure as the
108	hook_data parameter of the hook list creation function. That way, the hook will
109	be called with its hook_data as first parameter, which it can read and write. We
110	can think of this structure as the data related to the function that persists
111	between each call to the hook. You must make sure that you cast the hook_data to
112	the type of the structure before you use it in the hook function.
113	</P
114	><P
115	> The detail about how to access the different fields of the reading context (the
116	hook's call_data) will be discussed in the chapter "How to use the trace
117	reading context".
118	</P
119	></DIV
120	><DIV
121	CLASS="NAVFOOTER"
122	><HR
123	ALIGN="LEFT"
124	WIDTH="100%"><TABLE
125	SUMMARY="Footer navigation table"
126	WIDTH="100%"
127	BORDER="0"
128	CELLPADDING="0"
129	CELLSPACING="0"
130	><TR
131	><TD
132	WIDTH="33%"
133	ALIGN="left"
134	VALIGN="top"
135	><A
136	HREF="x23.html"
137	ACCESSKEY="P"
138	>Prev</A
139	></TD
140	><TD
141	WIDTH="34%"
142	ALIGN="center"
143	VALIGN="top"
144	><A
145	HREF="index.html"
146	ACCESSKEY="H"
147	>Home</A
148	></TD
149	><TD
150	WIDTH="33%"
151	ALIGN="right"
152	VALIGN="top"
153	><A
154	HREF="c40.html"
155	ACCESSKEY="N"
156	>Next</A
157	></TD
158	></TR
159	><TR
160	><TD
161	WIDTH="33%"
162	ALIGN="left"
163	VALIGN="top"
164	>A typical module</TD
165	><TD
166	WIDTH="34%"
167	ALIGN="center"
168	VALIGN="top"
169	><A
170	HREF="c18.html"
171	ACCESSKEY="U"
172	>Up</A
173	></TD
174	><TD
175	WIDTH="33%"
176	ALIGN="right"
177	VALIGN="top"
178	>How to use the Linux Trace Toolkit Viewer's Reading Context</TD
179	></TR
180	></TABLE
181	></DIV
182	></BODY
183	></HTML
184	>