DyninstAPI defensive mode manual update.
[dyninst.git] / instructionAPI / doc / latex / classDyninst_1_1InstructionAPI_1_1BinaryFunction.tex
1 \subsection{BinaryFunction Class}
2 \label{classDyninst_1_1InstructionAPI_1_1BinaryFunction}\index{Dyninst::InstructionAPI::BinaryFunction@{Dyninst::InstructionAPI::BinaryFunction}}
3 \subsubsection*{Public Member Functions}
4 \begin{DoxyCompactItemize}
5 \item 
6 {\textbf BinaryFunction} ({\textbf Expression::Ptr} arg1, {\textbf Expression::Ptr} arg2, Result\_\-Type result\_\-type, funcT::Ptr func)
7 \item 
8 virtual const {\textbf Result} \& {\textbf eval} () const 
9 \item 
10 virtual void {\textbf getChildren} (vector$<$ InstructionAST::Ptr $>$ \&children) const 
11 \item 
12 virtual void {\textbf getUses} (set$<$ InstructionAST::Ptr $>$ \&uses)
13 \item 
14 virtual bool {\textbf isUsed} (InstructionAST::Ptr findMe) const 
15 \end{DoxyCompactItemize}
16
17
18
19 A BinaryFunction object represents a function that can combine two Expressions and produce another ValueComputation.
20
21 For the purposes of representing a single operand of an instruction, the BinaryFunctions of interest are addition and multiplication of integer values; this allows a Expression to represent all addressing modes on the architectures currently supported by the Instruction API. 
22
23 \subsubsection{Constructors \& Destructors}
24 \index{Dyninst::InstructionAPI::BinaryFunction@{Dyninst::InstructionAPI::BinaryFunction}!BinaryFunction@{BinaryFunction}}
25 \index{BinaryFunction@{BinaryFunction}!Dyninst::InstructionAPI::BinaryFunction@{Dyninst::InstructionAPI::BinaryFunction}}
26 \paragraph[{BinaryFunction}]{\setlength{\rightskip}{0pt plus 5cm}{\textbf BinaryFunction} (
27 \begin{DoxyParamCaption}
28 \item[{{\textbf Expression::Ptr}}]{ arg1, }
29 \item[{{\textbf Expression::Ptr}}]{ arg2, }
30 \item[{Result\_\-Type}]{ result\_\-type, }
31 \item[{funcT::Ptr}]{ func}
32 \end{DoxyParamCaption}
33 )}\hfill\label{classDyninst_1_1InstructionAPI_1_1BinaryFunction_ac1d9ee9e075b29690d4f1f17949d94d0}
34
35 \begin{DoxyParams}{Parameters}
36 \item[{\em arg1}]first input to function \item[{\em arg2}]second input to function \item[{\em result\_\-type}]type of the function's result \item[{\em func}]implementation of the function\end{DoxyParams}
37 The constructor for a BinaryFunction may take a reference-\/counted pointer or a plain C++ pointer to each of the child Expressions that represent its arguments. Since the reference-\/counted implementation requires explicit construction, we provide overloads for all four combinations of plain and reference-\/counted pointers. Note that regardless of which constructor is used, the pointers {\ttfamily arg1} and {\ttfamily arg2} become owned by the BinaryFunction being constructed, and should not be deleted. They will be cleaned up when the BinaryFunction object is destroyed.
38
39 The {\ttfamily func} parameter is a binary functor on two Results. It should be derived from {\ttfamily funcT}. {\ttfamily addResult} and {\ttfamily multResult}, which respectively add and multiply two Results, are provided as part of the InstructionAPI, as they are necessary for representing address calculations. Other {\ttfamily funcTs} may be implemented by the user if desired. funcTs have names associated with them for output and debugging purposes. The addition and multiplication functors provided with the Instruction API are named \char`\"{}+\char`\"{} and \char`\"{}$\ast$\char`\"{}, respectively. 
40
41 \subsubsection{Member Functions}
42 \index{Dyninst::InstructionAPI::BinaryFunction@{Dyninst::InstructionAPI::BinaryFunction}!eval@{eval}}
43 \index{eval@{eval}!Dyninst::InstructionAPI::BinaryFunction@{Dyninst::InstructionAPI::BinaryFunction}}
44 \paragraph[{eval}]{\setlength{\rightskip}{0pt plus 5cm}const {\textbf Result} \& eval (
45 \begin{DoxyParamCaption}
46 {}
47 \end{DoxyParamCaption}
48 ) const\hspace{0.3cm}{\ttfamily  [virtual]}}\hfill\label{classDyninst_1_1InstructionAPI_1_1BinaryFunction_a9d6e92c2e65bf1162faa3734911ebff3}
49 The BinaryFunction version of {\ttfamily eval} allows the {\ttfamily eval} mechanism to handle complex addressing modes. Like all of the ValueComputation implementations, a BinaryFunction's {\ttfamily eval} will return the result of evaluating the expression it represents if possible, or an empty Result otherwise. A BinaryFunction may have arguments that can be evaluated, or arguments that cannot. Additionally, it may have a real function pointer, or it may have a null function pointer. If the arguments can be evaluated and the function pointer is real, a result other than an empty Result is guaranteed to be returned. This result is cached after its initial calculation; the caching mechanism also allows outside information to override the results of the BinaryFunction's internal computation. If the cached result exists, it is guaranteed to be returned even if the arguments or the function are not evaluable. 
50
51
52 \index{Dyninst::InstructionAPI::BinaryFunction@{Dyninst::InstructionAPI::BinaryFunction}!getChildren@{getChildren}}
53 \index{getChildren@{getChildren}!Dyninst::InstructionAPI::BinaryFunction@{Dyninst::InstructionAPI::BinaryFunction}}
54 \paragraph[{getChildren}]{\setlength{\rightskip}{0pt plus 5cm}virtual void getChildren (
55 \begin{DoxyParamCaption}
56 \item[{vector$<$ InstructionAST::Ptr $>$ \&}]{ children}
57 \end{DoxyParamCaption}
58 ) const\hspace{0.3cm}{\ttfamily  [virtual]}}\hfill\label{classDyninst_1_1InstructionAPI_1_1BinaryFunction_adabe6006766a7aaa6fa099f5f0ca5c0c}
59 The children of a BinaryFunction are its two arguments. 
60 \begin{DoxyParams}{Parameters}
61 \item[{\em children}]Appends the children of this BinaryFunction to {\ttfamily children}. \end{DoxyParams}
62
63
64
65 \index{Dyninst::InstructionAPI::BinaryFunction@{Dyninst::InstructionAPI::BinaryFunction}!getUses@{getUses}}
66 \index{getUses@{getUses}!Dyninst::InstructionAPI::BinaryFunction@{Dyninst::InstructionAPI::BinaryFunction}}
67 \paragraph[{getUses}]{\setlength{\rightskip}{0pt plus 5cm}virtual void getUses (
68 \begin{DoxyParamCaption}
69 \item[{set$<$ InstructionAST::Ptr $>$ \&}]{ uses}
70 \end{DoxyParamCaption}
71 )\hspace{0.3cm}{\ttfamily  [virtual]}}\hfill\label{classDyninst_1_1InstructionAPI_1_1BinaryFunction_a3793407f71d4fba12ae0af46e78da4b4}
72 The use set of a BinaryFunction is the union of the use sets of its children. 
73 \begin{DoxyParams}{Parameters}
74 \item[{\em uses}]Appends the use set of this BinaryFunction to {\ttfamily uses}. \end{DoxyParams}
75
76
77
78 \index{Dyninst::InstructionAPI::BinaryFunction@{Dyninst::InstructionAPI::BinaryFunction}!isUsed@{isUsed}}
79 \index{isUsed@{isUsed}!Dyninst::InstructionAPI::BinaryFunction@{Dyninst::InstructionAPI::BinaryFunction}}
80 \paragraph[{isUsed}]{\setlength{\rightskip}{0pt plus 5cm}virtual bool isUsed (
81 \begin{DoxyParamCaption}
82 \item[{InstructionAST::Ptr}]{ findMe}
83 \end{DoxyParamCaption}
84 ) const\hspace{0.3cm}{\ttfamily  [virtual]}}\hfill\label{classDyninst_1_1InstructionAPI_1_1BinaryFunction_af5b1db3ca39797ac0f619e04dd8bf9fc}
85 {\ttfamily isUsed} returns true if {\ttfamily findMe} is an argument of this BinaryFunction, or if it is in the use set of either argument. 
86
87