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