<ahref="SBValue_8h.html">Go to the documentation of this file.</a><divclass="fragment"><divclass="line"><aname="l00001"></a><spanclass="lineno"> 1</span> <spanclass="comment">//===-- SBValue.h -----------------------------------------------*- C++ -*-===//</span></div>
<divclass="line"><aname="l00005"></a><spanclass="lineno"> 5</span> <spanclass="comment">// This file is distributed under the University of Illinois Open Source</span></div>
<divclass="line"><aname="l00006"></a><spanclass="lineno"> 6</span> <spanclass="comment">// License. See LICENSE.TXT for details.</span></div>
<divclass="line"><aname="l00066"></a><spanclass="lineno"> 66</span> <spanclass="comment">// If you call this on a newly created ValueObject, it will always return</span></div>
<divclass="line"><aname="l00103"></a><spanclass="lineno"> 103</span> <spanclass="comment">// Deprecated - use the one that takes SBError&</span></div>
<divclass="line"><aname="l00123"></a><spanclass="lineno"> 123</span> <spanclass="comment">// Deprecated - use the expression evaluator to perform type casting</span></div>
<divclass="line"><aname="l00136"></a><spanclass="lineno"> 136</span> <spanclass="comment">// this has no address! GetAddress() and GetLoadAddress() as well as</span></div>
<divclass="line"><aname="l00138"></a><spanclass="lineno"> 138</span> <spanclass="comment">// on the return of this call all return invalid</span></div>
<divclass="line"><aname="l00143"></a><spanclass="lineno"> 143</span> <spanclass="comment"> /// Get a child value by index from a value.</span></div>
<divclass="line"><aname="l00148"></a><spanclass="lineno"> 148</span> <spanclass="comment"> /// Structs and unions access child members using a zero based index</span></div>
<divclass="line"><aname="l00149"></a><spanclass="lineno"> 149</span> <spanclass="comment"> /// for each child member. For</span></div>
<divclass="line"><aname="l00151"></a><spanclass="lineno"> 151</span> <spanclass="comment"> /// Classes reserve the first indexes for base classes that have</span></div>
<divclass="line"><aname="l00152"></a><spanclass="lineno"> 152</span> <spanclass="comment"> /// members (empty base classes are omitted), and all members of the</span></div>
<divclass="line"><aname="l00153"></a><spanclass="lineno"> 153</span> <spanclass="comment"> /// current class will then follow the base classes.</span></div>
<divclass="line"><aname="l00155"></a><spanclass="lineno"> 155</span> <spanclass="comment"> /// Pointers differ depending on what they point to. If the pointer</span></div>
<divclass="line"><aname="l00156"></a><spanclass="lineno"> 156</span> <spanclass="comment"> /// points to a simple type, the child at index zero</span></div>
<divclass="line"><aname="l00157"></a><spanclass="lineno"> 157</span> <spanclass="comment"> /// is the only child value available, unless \a synthetic_allowed</span></div>
<divclass="line"><aname="l00158"></a><spanclass="lineno"> 158</span> <spanclass="comment"> /// is \b true, in which case the pointer will be used as an array</span></div>
<divclass="line"><aname="l00159"></a><spanclass="lineno"> 159</span> <spanclass="comment"> /// and can create 'synthetic' child values using positive or</span></div>
<divclass="line"><aname="l00160"></a><spanclass="lineno"> 160</span> <spanclass="comment"> /// negative indexes. If the pointer points to an aggregate type</span></div>
<divclass="line"><aname="l00161"></a><spanclass="lineno"> 161</span> <spanclass="comment"> /// (an array, class, union, struct), then the pointee is</span></div>
<divclass="line"><aname="l00162"></a><spanclass="lineno"> 162</span> <spanclass="comment"> /// transparently skipped and any children are going to be the indexes</span></div>
<divclass="line"><aname="l00163"></a><spanclass="lineno"> 163</span> <spanclass="comment"> /// of the child values within the aggregate type. For example if</span></div>
<divclass="line"><aname="l00164"></a><spanclass="lineno"> 164</span> <spanclass="comment"> /// we have a 'Point' type and we have a SBValue that contains a</span></div>
<divclass="line"><aname="l00165"></a><spanclass="lineno"> 165</span> <spanclass="comment"> /// pointer to a 'Point' type, then the child at index zero will be</span></div>
<divclass="line"><aname="l00166"></a><spanclass="lineno"> 166</span> <spanclass="comment"> /// the 'x' member, and the child at index 1 will be the 'y' member</span></div>
<divclass="line"><aname="l00167"></a><spanclass="lineno"> 167</span> <spanclass="comment"> /// (the child at index zero won't be a 'Point' instance).</span></div>
<divclass="line"><aname="l00169"></a><spanclass="lineno"> 169</span> <spanclass="comment"> /// If you actually need an SBValue that represents the type pointed</span></div>
<divclass="line"><aname="l00170"></a><spanclass="lineno"> 170</span> <spanclass="comment"> /// to by a SBValue for which GetType().IsPointeeType() returns true,</span></div>
<divclass="line"><aname="l00171"></a><spanclass="lineno"> 171</span> <spanclass="comment"> /// regardless of the pointee type, you can do that with SBValue::Dereference.</span></div>
<divclass="line"><aname="l00173"></a><spanclass="lineno"> 173</span> <spanclass="comment"> /// Arrays have a preset number of children that can be accessed by</span></div>
<divclass="line"><aname="l00174"></a><spanclass="lineno"> 174</span> <spanclass="comment"> /// index and will returns invalid child values for indexes that are</span></div>
<divclass="line"><aname="l00175"></a><spanclass="lineno"> 175</span> <spanclass="comment"> /// out of bounds unless the \a synthetic_allowed is \b true. In this</span></div>
<divclass="line"><aname="l00176"></a><spanclass="lineno"> 176</span> <spanclass="comment"> /// case the array can create 'synthetic' child values for indexes</span></div>
<divclass="line"><aname="l00177"></a><spanclass="lineno"> 177</span> <spanclass="comment"> /// that aren't in the array bounds using positive or negative</span></div>
<divclass="line"><aname="l00184"></a><spanclass="lineno"> 184</span> <spanclass="comment"> /// An enumeration that specifies whether to get dynamic values,</span></div>
<divclass="line"><aname="l00185"></a><spanclass="lineno"> 185</span> <spanclass="comment"> /// and also if the target can be run to figure out the dynamic</span></div>
<divclass="line"><aname="l00186"></a><spanclass="lineno"> 186</span> <spanclass="comment"> /// type of the child value.</span></div>
<divclass="line"><aname="l00189"></a><spanclass="lineno"> 189</span> <spanclass="comment"> /// If \b true, then allow child values to be created by index</span></div>
<divclass="line"><aname="l00190"></a><spanclass="lineno"> 190</span> <spanclass="comment"> /// for pointers and arrays for indexes that normally wouldn't</span></div>
<divclass="line"><aname="l00191"></a><spanclass="lineno"> 191</span> <spanclass="comment"> /// be allowed.</span></div>
<divclass="line"><aname="l00194"></a><spanclass="lineno"> 194</span> <spanclass="comment"> /// A new SBValue object that represents the child member value.</span></div>
<divclass="line"><aname="l00200"></a><spanclass="lineno"> 200</span> <spanclass="comment">// Matches children of this object only and will match base classes and</span></div>
<divclass="line"><aname="l00201"></a><spanclass="lineno"> 201</span> <spanclass="comment">// member names if this is a clang typed object.</span></div>
<divclass="line"><aname="l00204"></a><spanclass="lineno"> 204</span> <spanclass="comment">// Matches child members of this object and child members of any base</span></div>
<divclass="line"><aname="l00208"></a><spanclass="lineno"> 208</span> <spanclass="comment">// Matches child members of this object and child members of any base</span></div>
<divclass="line"><aname="l00223"></a><spanclass="lineno"> 223</span> <spanclass="comment"> /// Get an SBData wrapping what this SBValue points to.</span></div>
<divclass="line"><aname="l00225"></a><spanclass="lineno"> 225</span> <spanclass="comment"> /// This method will dereference the current SBValue, if its</span></div>
<divclass="line"><aname="l00226"></a><spanclass="lineno"> 226</span> <spanclass="comment"> /// data type is a T* or T[], and extract item_count elements</span></div>
<divclass="line"><aname="l00227"></a><spanclass="lineno"> 227</span> <spanclass="comment"> /// of type T from it, copying their contents in an SBData.</span></div>
<divclass="line"><aname="l00230"></a><spanclass="lineno"> 230</span> <spanclass="comment"> /// The index of the first item to retrieve. For an array</span></div>
<divclass="line"><aname="l00231"></a><spanclass="lineno"> 231</span> <spanclass="comment"> /// this is equivalent to array[item_idx], for a pointer</span></div>
<divclass="line"><aname="l00232"></a><spanclass="lineno"> 232</span> <spanclass="comment"> /// to *(pointer + item_idx). In either case, the measurement</span></div>
<divclass="line"><aname="l00233"></a><spanclass="lineno"> 233</span> <spanclass="comment"> /// unit for item_idx is the sizeof(T) rather than the byte</span></div>
<divclass="line"><aname="l00236"></a><spanclass="lineno"> 236</span> <spanclass="comment"> /// How many items should be copied into the output. By default</span></div>
<divclass="line"><aname="l00237"></a><spanclass="lineno"> 237</span> <spanclass="comment"> /// only one item is copied, but more can be asked for.</span></div>
<divclass="line"><aname="l00240"></a><spanclass="lineno"> 240</span> <spanclass="comment"> /// An SBData with the contents of the copied items, on success.</span></div>
<divclass="line"><aname="l00241"></a><spanclass="lineno"> 241</span> <spanclass="comment"> /// An empty SBData otherwise.</span></div>
<divclass="line"><aname="l00246"></a><spanclass="lineno"> 246</span> <spanclass="comment"> /// Get an SBData wrapping the contents of this SBValue.</span></div>
<divclass="line"><aname="l00248"></a><spanclass="lineno"> 248</span> <spanclass="comment"> /// This method will read the contents of this object in memory</span></div>
<divclass="line"><aname="l00249"></a><spanclass="lineno"> 249</span> <spanclass="comment"> /// and copy them into an SBData for future use.</span></div>
<divclass="line"><aname="l00252"></a><spanclass="lineno"> 252</span> <spanclass="comment"> /// An SBData with the contents of this SBValue, on success.</span></div>
<divclass="line"><aname="l00253"></a><spanclass="lineno"> 253</span> <spanclass="comment"> /// An empty SBData otherwise.</span></div>
<divclass="line"><aname="l00262"></a><spanclass="lineno"> 262</span> <spanclass="comment"> /// Find out if a SBValue might have children.</span></div>
<divclass="line"><aname="l00264"></a><spanclass="lineno"> 264</span> <spanclass="comment"> /// This call is much more efficient than GetNumChildren() as it</span></div>
<divclass="line"><aname="l00265"></a><spanclass="lineno"> 265</span> <spanclass="comment"> /// doesn't need to complete the underlying type. This is designed</span></div>
<divclass="line"><aname="l00266"></a><spanclass="lineno"> 266</span> <spanclass="comment"> /// to be used in a UI environment in order to detect if the</span></div>
<divclass="line"><aname="l00267"></a><spanclass="lineno"> 267</span> <spanclass="comment"> /// disclosure triangle should be displayed or not.</span></div>
<divclass="line"><aname="l00269"></a><spanclass="lineno"> 269</span> <spanclass="comment"> /// This function returns true for class, union, structure,</span></div>
<divclass="line"><aname="l00270"></a><spanclass="lineno"> 270</span> <spanclass="comment"> /// pointers, references, arrays and more. Again, it does so without</span></div>
<divclass="line"><aname="l00271"></a><spanclass="lineno"> 271</span> <spanclass="comment"> /// doing any expensive type completion.</span></div>
<divclass="line"><aname="l00274"></a><spanclass="lineno"> 274</span> <spanclass="comment"> /// Returns \b true if the SBValue might have children, or \b</span></div>
<divclass="line"><aname="l00314"></a><spanclass="lineno"> 314</span> <spanclass="comment"> /// Watch this value if it resides in memory.</span></div>
<divclass="line"><aname="l00319"></a><spanclass="lineno"> 319</span> <spanclass="comment"> /// Resolve the location of this value once and watch its address.</span></div>
<divclass="line"><aname="l00320"></a><spanclass="lineno"> 320</span> <spanclass="comment"> /// This value must currently be set to \b true as watching all</span></div>
<divclass="line"><aname="l00321"></a><spanclass="lineno"> 321</span> <spanclass="comment"> /// locations of a variable or a variable path is not yet supported,</span></div>
<divclass="line"><aname="l00322"></a><spanclass="lineno"> 322</span> <spanclass="comment"> /// though we plan to support it in the future.</span></div>
<divclass="line"><aname="l00331"></a><spanclass="lineno"> 331</span> <spanclass="comment"> /// An error object. Contains the reason if there is some failure.</span></div>
<divclass="line"><aname="l00334"></a><spanclass="lineno"> 334</span> <spanclass="comment"> /// An SBWatchpoint object. This object might not be valid upon</span></div>
<divclass="line"><aname="l00335"></a><spanclass="lineno"> 335</span> <spanclass="comment"> /// return due to a value not being contained in memory, too</span></div>
<divclass="line"><aname="l00336"></a><spanclass="lineno"> 336</span> <spanclass="comment"> /// large, or watchpoint resources are not available or all in</span></div>
<divclass="line"><aname="l00342"></a><spanclass="lineno"> 342</span> <spanclass="comment">// Backward compatibility fix in the interim.</span></div>
<divclass="line"><aname="l00346"></a><spanclass="lineno"> 346</span> <spanclass="comment"> /// Watch this value that this value points to in memory</span></div>
<divclass="line"><aname="l00351"></a><spanclass="lineno"> 351</span> <spanclass="comment"> /// Resolve the location of this value once and watch its address.</span></div>
<divclass="line"><aname="l00352"></a><spanclass="lineno"> 352</span> <spanclass="comment"> /// This value must currently be set to \b true as watching all</span></div>
<divclass="line"><aname="l00353"></a><spanclass="lineno"> 353</span> <spanclass="comment"> /// locations of a variable or a variable path is not yet supported,</span></div>
<divclass="line"><aname="l00354"></a><spanclass="lineno"> 354</span> <spanclass="comment"> /// though we plan to support it in the future.</span></div>
<divclass="line"><aname="l00363"></a><spanclass="lineno"> 363</span> <spanclass="comment"> /// An error object. Contains the reason if there is some failure.</span></div>
<divclass="line"><aname="l00366"></a><spanclass="lineno"> 366</span> <spanclass="comment"> /// An SBWatchpoint object. This object might not be valid upon</span></div>
<divclass="line"><aname="l00367"></a><spanclass="lineno"> 367</span> <spanclass="comment"> /// return due to a value not being contained in memory, too</span></div>
<divclass="line"><aname="l00368"></a><spanclass="lineno"> 368</span> <spanclass="comment"> /// large, or watchpoint resources are not available or all in</span></div>
<divclass="line"><aname="l00375"></a><spanclass="lineno"> 375</span> <spanclass="comment"> /// Same as the protected version of GetSP that takes a locker, except that we</span></div>
<divclass="line"><aname="l00376"></a><spanclass="lineno"> 376</span> <spanclass="comment"> /// make the</span></div>
<divclass="line"><aname="l00377"></a><spanclass="lineno"> 377</span> <spanclass="comment"> /// locker locally in the function. Since the Target API mutex is recursive,</span></div>
<divclass="line"><aname="l00378"></a><spanclass="lineno"> 378</span> <spanclass="comment"> /// and the</span></div>
<divclass="line"><aname="l00379"></a><spanclass="lineno"> 379</span> <spanclass="comment"> /// StopLocker is a read lock, you can call this function even if you are</span></div>
<divclass="line"><aname="l00381"></a><spanclass="lineno"> 381</span> <spanclass="comment"> /// holding the two above-mentioned locks.</span></div>
<divclass="line"><aname="l00384"></a><spanclass="lineno"> 384</span> <spanclass="comment"> /// A ValueObjectSP of the best kind (static, dynamic or synthetic) we</span></div>
<divclass="line"><aname="l00385"></a><spanclass="lineno"> 385</span> <spanclass="comment"> /// can cons up, in accordance with the SBValue's settings.</span></div>
<divclass="line"><aname="l00397"></a><spanclass="lineno"> 397</span> <spanclass="comment"> /// Get the appropriate ValueObjectSP from this SBValue, consulting the</span></div>
<divclass="line"><aname="l00398"></a><spanclass="lineno"> 398</span> <spanclass="comment"> /// use_dynamic and use_synthetic options passed in to SetSP when the</span></div>
<divclass="line"><aname="l00399"></a><spanclass="lineno"> 399</span> <spanclass="comment"> /// SBValue's contents were set. Since this often requires examining memory,</span></div>
<divclass="line"><aname="l00400"></a><spanclass="lineno"> 400</span> <spanclass="comment"> /// and maybe even running code, it needs to acquire the Target API and</span></div>
<divclass="line"><aname="l00401"></a><spanclass="lineno"> 401</span> <spanclass="comment"> /// Process StopLock.</span></div>
<divclass="line"><aname="l00402"></a><spanclass="lineno"> 402</span> <spanclass="comment"> /// Those are held in an opaque class ValueLocker which is currently local to</span></div>
<divclass="line"><aname="l00404"></a><spanclass="lineno"> 404</span> <spanclass="comment"> /// So you don't have to get these yourself just default construct a</span></div>
<divclass="line"><aname="l00405"></a><spanclass="lineno"> 405</span> <spanclass="comment"> /// ValueLocker, and pass it into this.</span></div>
<divclass="line"><aname="l00406"></a><spanclass="lineno"> 406</span> <spanclass="comment"> /// If we need to make a ValueLocker and use it in some other .cpp file, we'll</span></div>
<divclass="line"><aname="l00407"></a><spanclass="lineno"> 407</span> <spanclass="comment"> /// have to move it to</span></div>
<divclass="line"><aname="l00408"></a><spanclass="lineno"> 408</span> <spanclass="comment"> /// ValueObject.h/cpp or somewhere else convenient. We haven't needed to so</span></div>
<divclass="line"><aname="l00412"></a><spanclass="lineno"> 412</span> <spanclass="comment"> /// An object that will hold the Target API, and Process RunLocks, and</span></div>
<divclass="line"><aname="l00413"></a><spanclass="lineno"> 413</span> <spanclass="comment"> /// auto-destroy them when it goes out of scope. Currently this is only</span></div>
<divclass="line"><aname="l00418"></a><spanclass="lineno"> 418</span> <spanclass="comment"> /// A ValueObjectSP of the best kind (static, dynamic or synthetic) we</span></div>
<divclass="line"><aname="l00419"></a><spanclass="lineno"> 419</span> <spanclass="comment"> /// can cons up, in accordance with the SBValue's settings.</span></div>
<divclass="line"><aname="l00423"></a><spanclass="lineno"> 423</span> <spanclass="comment">// these calls do the right thing WRT adjusting their settings according to</span></div>
<divclass="line"><aname="l00424"></a><spanclass="lineno"> 424</span> <spanclass="comment">// the target's preferences</span></div>
