contrib/llvm/tools/lldb/include/lldb/API/SBValue.h

   1 //===-- SBValue.h -----------------------------------------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9
  10 #ifndef LLDB_SBValue_h_
  11 #define LLDB_SBValue_h_
  12
  13 #include "lldb/API/SBData.h"
  14 #include "lldb/API/SBDefines.h"
  15 #include "lldb/API/SBType.h"
  16
  17 class ValueImpl;
  18 class ValueLocker;
  19
  20 namespace lldb {
  21
  22 class SBValue
  23 {
  24 friend class ValueLocker;
  25
  26 public:
  27     SBValue ();
  28
  29     SBValue (const lldb::SBValue &rhs);
  30
  31     lldb::SBValue &
  32     operator =(const lldb::SBValue &rhs);
  33
  34     ~SBValue ();
  35
  36     bool
  37     IsValid();
  38
  39     void
  40     Clear();
  41
  42     SBError
  43     GetError();
  44
  45     lldb::user_id_t
  46     GetID ();
  47
  48     const char *
  49     GetName();
  50
  51     const char *
  52     GetTypeName ();
  53
  54     size_t
  55     GetByteSize ();
  56
  57     bool
  58     IsInScope ();
  59
  60     lldb::Format
  61     GetFormat ();
  62
  63     void
  64     SetFormat (lldb::Format format);
  65
  66     const char *
  67     GetValue ();
  68
  69     int64_t
  70     GetValueAsSigned (lldb::SBError& error, int64_t fail_value=0);
  71
  72     uint64_t
  73     GetValueAsUnsigned (lldb::SBError& error, uint64_t fail_value=0);
  74
  75     int64_t
  76     GetValueAsSigned(int64_t fail_value=0);
  77
  78     uint64_t
  79     GetValueAsUnsigned(uint64_t fail_value=0);
  80
  81     ValueType
  82     GetValueType ();
  83
  84     bool
  85     GetValueDidChange ();
  86
  87     const char *
  88     GetSummary ();
  89
  90     const char *
  91     GetObjectDescription ();
  92
  93     lldb::SBValue
  94     GetDynamicValue (lldb::DynamicValueType use_dynamic);
  95
  96     lldb::SBValue
  97     GetStaticValue ();
  98
  99     lldb::SBValue
 100     GetNonSyntheticValue ();
 101
 102     lldb::DynamicValueType
 103     GetPreferDynamicValue ();
 104
 105     void
 106     SetPreferDynamicValue (lldb::DynamicValueType use_dynamic);
 107
 108     bool
 109     GetPreferSyntheticValue ();
 110
 111     void
 112     SetPreferSyntheticValue (bool use_synthetic);
 113
 114     bool
 115     IsDynamic ();
 116
 117     bool
 118     IsSynthetic ();
 119
 120     const char *
 121     GetLocation ();
 122
 123     // Deprecated - use the one that takes SBError&
 124     bool
 125     SetValueFromCString (const char *value_str);
 126
 127     bool
 128     SetValueFromCString (const char *value_str, lldb::SBError& error);
 129
 130     lldb::SBTypeFormat
 131     GetTypeFormat ();
 132
 133 #ifndef LLDB_DISABLE_PYTHON
 134     lldb::SBTypeSummary
 135     GetTypeSummary ();
 136 #endif
 137
 138     lldb::SBTypeFilter
 139     GetTypeFilter ();
 140
 141 #ifndef LLDB_DISABLE_PYTHON
 142     lldb::SBTypeSynthetic
 143     GetTypeSynthetic ();
 144 #endif
 145
 146     lldb::SBValue
 147     GetChildAtIndex (uint32_t idx);
 148
 149     lldb::SBValue
 150     CreateChildAtOffset (const char *name, uint32_t offset, lldb::SBType type);
 151
 152     lldb::SBValue
 153     Cast (lldb::SBType type);
 154
 155     lldb::SBValue
 156     CreateValueFromExpression (const char *name, const char* expression);
 157
 158     lldb::SBValue
 159     CreateValueFromExpression (const char *name, const char* expression, SBExpressionOptions &options);
 160
 161     lldb::SBValue
 162     CreateValueFromAddress (const char* name,
 163                             lldb::addr_t address,
 164                             lldb::SBType type);
 165
 166     // this has no address! GetAddress() and GetLoadAddress() as well as AddressOf()
 167     // on the return of this call all return invalid
 168     lldb::SBValue
 169     CreateValueFromData (const char* name,
 170                          lldb::SBData data,
 171                          lldb::SBType type);
 172
 173     //------------------------------------------------------------------
 174     /// Get a child value by index from a value.
 175     ///
 176     /// Structs, unions, classes, arrays and and pointers have child
 177     /// values that can be access by index.
 178     ///
 179     /// Structs and unions access child members using a zero based index
 180     /// for each child member. For
 181     ///
 182     /// Classes reserve the first indexes for base classes that have
 183     /// members (empty base classes are omitted), and all members of the
 184     /// current class will then follow the base classes.
 185     ///
 186     /// Pointers differ depending on what they point to. If the pointer
 187     /// points to a simple type, the child at index zero
 188     /// is the only child value available, unless \a synthetic_allowed
 189     /// is \b true, in which case the pointer will be used as an array
 190     /// and can create 'synthetic' child values using positive or
 191     /// negative indexes. If the pointer points to an aggregate type
 192     /// (an array, class, union, struct), then the pointee is
 193     /// transparently skipped and any children are going to be the indexes
 194     /// of the child values within the aggregate type. For example if
 195     /// we have a 'Point' type and we have a SBValue that contains a
 196     /// pointer to a 'Point' type, then the child at index zero will be
 197     /// the 'x' member, and the child at index 1 will be the 'y' member
 198     /// (the child at index zero won't be a 'Point' instance).
 199     ///
 200     /// Arrays have a preset number of children that can be accessed by
 201     /// index and will returns invalid child values for indexes that are
 202     /// out of bounds unless the \a synthetic_allowed is \b true. In this
 203     /// case the array can create 'synthetic' child values for indexes
 204     /// that aren't in the array bounds using positive or negative
 205     /// indexes.
 206     ///
 207     /// @param[in] idx
 208     ///     The index of the child value to get
 209     ///
 210     /// @param[in] use_dynamic
 211     ///     An enumeration that specifies wether to get dynamic values,
 212     ///     and also if the target can be run to figure out the dynamic
 213     ///     type of the child value.
 214     ///
 215     /// @param[in] synthetic_allowed
 216     ///     If \b true, then allow child values to be created by index
 217     ///     for pointers and arrays for indexes that normally wouldn't
 218     ///     be allowed.
 219     ///
 220     /// @return
 221     ///     A new SBValue object that represents the child member value.
 222     //------------------------------------------------------------------
 223     lldb::SBValue
 224     GetChildAtIndex (uint32_t idx,
 225                      lldb::DynamicValueType use_dynamic,
 226                      bool can_create_synthetic);
 227
 228     // Matches children of this object only and will match base classes and
 229     // member names if this is a clang typed object.
 230     uint32_t
 231     GetIndexOfChildWithName (const char *name);
 232
 233     // Matches child members of this object and child members of any base
 234     // classes.
 235     lldb::SBValue
 236     GetChildMemberWithName (const char *name);
 237
 238     // Matches child members of this object and child members of any base
 239     // classes.
 240     lldb::SBValue
 241     GetChildMemberWithName (const char *name, lldb::DynamicValueType use_dynamic);
 242
 243     // Expands nested expressions like .a->b[0].c[1]->d
 244     lldb::SBValue
 245     GetValueForExpressionPath(const char* expr_path);
 246
 247     lldb::SBValue
 248     AddressOf();
 249
 250     lldb::addr_t
 251     GetLoadAddress();
 252
 253     lldb::SBAddress
 254     GetAddress();
 255
 256     //------------------------------------------------------------------
 257     /// Get an SBData wrapping what this SBValue points to.
 258     ///
 259     /// This method will dereference the current SBValue, if its
 260     /// data type is a T* or T[], and extract item_count elements
 261     /// of type T from it, copying their contents in an SBData.
 262     ///
 263     /// @param[in] item_idx
 264     ///     The index of the first item to retrieve. For an array
 265     ///     this is equivalent to array[item_idx], for a pointer
 266     ///     to *(pointer + item_idx). In either case, the measurement
 267     ///     unit for item_idx is the sizeof(T) rather than the byte
 268     ///
 269     /// @param[in] item_count
 270     ///     How many items should be copied into the output. By default
 271     ///     only one item is copied, but more can be asked for.
 272     ///
 273     /// @return
 274     ///     An SBData with the contents of the copied items, on success.
 275     ///     An empty SBData otherwise.
 276     //------------------------------------------------------------------
 277     lldb::SBData
 278     GetPointeeData (uint32_t item_idx = 0,
 279                     uint32_t item_count = 1);
 280
 281     //------------------------------------------------------------------
 282     /// Get an SBData wrapping the contents of this SBValue.
 283     ///
 284     /// This method will read the contents of this object in memory
 285     /// and copy them into an SBData for future use.
 286     ///
 287     /// @return
 288     ///     An SBData with the contents of this SBValue, on success.
 289     ///     An empty SBData otherwise.
 290     //------------------------------------------------------------------
 291     lldb::SBData
 292     GetData ();
 293
 294     bool
 295     SetData (lldb::SBData &data, lldb::SBError& error);
 296
 297     lldb::SBDeclaration
 298     GetDeclaration ();
 299
 300     //------------------------------------------------------------------
 301     /// Find out if a SBValue might have children.
 302     ///
 303     /// This call is much more efficient than GetNumChildren() as it
 304     /// doesn't need to complete the underlying type. This is designed
 305     /// to be used in a UI environment in order to detect if the
 306     /// disclosure triangle should be displayed or not.
 307     ///
 308     /// This function returns true for class, union, structure,
 309     /// pointers, references, arrays and more. Again, it does so without
 310     /// doing any expensive type completion.
 311     ///
 312     /// @return
 313     ///     Returns \b true if the SBValue might have children, or \b
 314     ///     false otherwise.
 315     //------------------------------------------------------------------
 316     bool
 317     MightHaveChildren ();
 318
 319     uint32_t
 320     GetNumChildren ();
 321
 322     void *
 323     GetOpaqueType();
 324
 325     lldb::SBTarget
 326     GetTarget();
 327
 328     lldb::SBProcess
 329     GetProcess();
 330
 331     lldb::SBThread
 332     GetThread();
 333
 334     lldb::SBFrame
 335     GetFrame();
 336
 337     lldb::SBValue
 338     Dereference ();
 339
 340     bool
 341     TypeIsPointerType ();
 342
 343     lldb::SBType
 344     GetType();
 345
 346     bool
 347     GetDescription (lldb::SBStream &description);
 348
 349     bool
 350     GetExpressionPath (lldb::SBStream &description);
 351
 352     bool
 353     GetExpressionPath (lldb::SBStream &description,
 354                        bool qualify_cxx_base_classes);
 355
 356     SBValue (const lldb::ValueObjectSP &value_sp);
 357
 358     //------------------------------------------------------------------
 359     /// Watch this value if it resides in memory.
 360     ///
 361     /// Sets a watchpoint on the value.
 362     ///
 363     /// @param[in] resolve_location
 364     ///     Resolve the location of this value once and watch its address.
 365     ///     This value must currently be set to \b true as watching all
 366     ///     locations of a variable or a variable path is not yet supported,
 367     ///     though we plan to support it in the future.
 368     ///
 369     /// @param[in] read
 370     ///     Stop when this value is accessed.
 371     ///
 372     /// @param[in] write
 373     ///     Stop when this value is modified
 374     ///
 375     /// @param[out]
 376     ///     An error object. Contains the reason if there is some failure.
 377     ///
 378     /// @return
 379     ///     An SBWatchpoint object. This object might not be valid upon
 380     ///     return due to a value not being contained in memory, too
 381     ///     large, or watchpoint resources are not available or all in
 382     ///     use.
 383     //------------------------------------------------------------------
 384     lldb::SBWatchpoint
 385     Watch (bool resolve_location, bool read, bool write, SBError &error);
 386
 387     // Backward compatibility fix in the interim.
 388     lldb::SBWatchpoint
 389     Watch (bool resolve_location, bool read, bool write);
 390
 391     //------------------------------------------------------------------
 392     /// Watch this value that this value points to in memory
 393     ///
 394     /// Sets a watchpoint on the value.
 395     ///
 396     /// @param[in] resolve_location
 397     ///     Resolve the location of this value once and watch its address.
 398     ///     This value must currently be set to \b true as watching all
 399     ///     locations of a variable or a variable path is not yet supported,
 400     ///     though we plan to support it in the future.
 401     ///
 402     /// @param[in] read
 403     ///     Stop when this value is accessed.
 404     ///
 405     /// @param[in] write
 406     ///     Stop when this value is modified
 407     ///
 408     /// @param[out]
 409     ///     An error object. Contains the reason if there is some failure.
 410     ///
 411     /// @return
 412     ///     An SBWatchpoint object. This object might not be valid upon
 413     ///     return due to a value not being contained in memory, too
 414     ///     large, or watchpoint resources are not available or all in
 415     ///     use.
 416     //------------------------------------------------------------------
 417     lldb::SBWatchpoint
 418     WatchPointee (bool resolve_location, bool read, bool write, SBError &error);
 419
 420     //------------------------------------------------------------------
 421     /// Same as the protected version of GetSP that takes a locker, except that we make the
 422     /// locker locally in the function.  Since the Target API mutex is recursive, and the
 423     /// StopLocker is a read lock, you can call this function even if you are already
 424     /// holding the two above-mentioned locks.
 425     ///
 426     /// @return
 427     ///     A ValueObjectSP of the best kind (static, dynamic or synthetic) we
 428     ///     can cons up, in accordance with the SBValue's settings.
 429     //------------------------------------------------------------------
 430     lldb::ValueObjectSP
 431     GetSP () const;
 432
 433 protected:
 434     friend class SBBlock;
 435     friend class SBFrame;
 436     friend class SBTarget;
 437     friend class SBThread;
 438     friend class SBValueList;
 439
 440     //------------------------------------------------------------------
 441     /// Get the appropriate ValueObjectSP from this SBValue, consulting the
 442     /// use_dynamic and use_synthetic options passed in to SetSP when the
 443     /// SBValue's contents were set.  Since this often requires examining memory,
 444     /// and maybe even running code, it needs to acquire the Target API and Process StopLock.
 445     /// Those are held in an opaque class ValueLocker which is currently local to SBValue.cpp.
 446     /// So you don't have to get these yourself just default construct a ValueLocker, and pass it into this.
 447     /// If we need to make a ValueLocker and use it in some other .cpp file, we'll have to move it to
 448     /// ValueObject.h/cpp or somewhere else convenient.  We haven't needed to so far.
 449     ///
 450     /// @param[in] value_locker
 451     ///     An object that will hold the Target API, and Process RunLocks, and
 452     ///     auto-destroy them when it goes out of scope.  Currently this is only useful in
 453     ///     SBValue.cpp.
 454     ///
 455     /// @return
 456     ///     A ValueObjectSP of the best kind (static, dynamic or synthetic) we
 457     ///     can cons up, in accordance with the SBValue's settings.
 458     //------------------------------------------------------------------
 459     lldb::ValueObjectSP
 460     GetSP (ValueLocker &value_locker) const;
 461
 462     // these calls do the right thing WRT adjusting their settings according to the target's preferences
 463     void
 464     SetSP (const lldb::ValueObjectSP &sp);
 465
 466     void
 467     SetSP (const lldb::ValueObjectSP &sp, bool use_synthetic);
 468
 469     void
 470     SetSP (const lldb::ValueObjectSP &sp, lldb::DynamicValueType use_dynamic);
 471
 472     void
 473     SetSP (const lldb::ValueObjectSP &sp, lldb::DynamicValueType use_dynamic, bool use_synthetic);
 474
 475     void
 476     SetSP (const lldb::ValueObjectSP &sp, lldb::DynamicValueType use_dynamic, bool use_synthetic, const char *name);
 477
 478 private:
 479     typedef std::shared_ptr<ValueImpl> ValueImplSP;
 480     ValueImplSP m_opaque_sp;
 481
 482     void
 483     SetSP (ValueImplSP impl_sp);
 484 };
 485
 486 } // namespace lldb
 487
 488 #endif  // LLDB_SBValue_h_