[Lldb-commits] [lldb] r139487 - in /lldb/trunk: include/lldb/Core/ConstString.h source/Core/ConstString.cpp
Greg Clayton
gclayton at apple.com
Sun Sep 11 20:55:58 PDT 2011
Author: gclayton
Date: Sun Sep 11 22:55:58 2011
New Revision: 139487
URL: http://llvm.org/viewvc/llvm-project?rev=139487&view=rev
Log:
Fixed up the comments in the headerdoc to match the current implementation
of how ConstString objects work, and removed the duplicate and out of date
comments that were in the cpp file.
Modified:
lldb/trunk/include/lldb/Core/ConstString.h
lldb/trunk/source/Core/ConstString.cpp
Modified: lldb/trunk/include/lldb/Core/ConstString.h
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/include/lldb/Core/ConstString.h?rev=139487&r1=139486&r2=139487&view=diff
==============================================================================
--- lldb/trunk/include/lldb/Core/ConstString.h (original)
+++ lldb/trunk/include/lldb/Core/ConstString.h Sun Sep 11 22:55:58 2011
@@ -23,11 +23,15 @@
/// @class ConstString ConstString.h "lldb/Core/ConstString.h"
/// @brief A uniqued constant string class.
///
-/// Provides an efficient way to store strings as uniqued ref counted
-/// strings. Since the strings are uniqued, finding strings that are
-/// equal to one another is very fast (pointer compares). It also allows
-/// for many common strings from many different sources to be shared to
-/// keep the memory footprint low.
+/// Provides an efficient way to store strings as uniqued strings. After
+/// the strings are uniqued, finding strings that are equal to one
+/// another is very fast as just the pointers need to be compared. It
+/// also allows for many common strings from many different sources to
+/// be shared to keep the memory footprint low.
+///
+/// No reference counting is done on strings that are added to the
+/// string pool, once strings are added they are in the string pool for
+/// the life of the program.
//----------------------------------------------------------------------
class ConstString
{
@@ -46,8 +50,7 @@
//------------------------------------------------------------------
/// Copy constructor
///
- /// Copies the string value in \a rhs and retains an extra reference
- /// to the string value in the string pool.
+ /// Copies the string value in \a rhs into this object.
///
/// @param[in] rhs
/// Another string object to copy.
@@ -61,10 +64,8 @@
/// Construct with C String value
///
/// Constructs this object with a C string by looking to see if the
- /// C string already exists in the global string pool. If it does
- /// exist, it retains an extra reference to the string in the string
- /// pool. If it doesn't exist, it is added to the string pool with
- /// a reference count of 1.
+ /// C string already exists in the global string pool. If it doesn't
+ /// exist, it is added to the string pool.
///
/// @param[in] cstr
/// A NULL terminated C string to add to the string pool.
@@ -80,13 +81,12 @@
/// be created without the need to NULL terminate the string as it
/// is passed into this function.
///
- /// If the C string already exists in the global string pool, it
- /// retains an extra reference to the string in the string
- /// pool. If it doesn't exist, it is added to the string pool with
- /// a reference count of 1.
- ///
/// @param[in] cstr
- /// A NULL terminated C string to add to the string pool.
+ /// A pointer to the first character in the C string. The C
+ /// string can be NULL terminated in a buffer that contains
+ /// more characters than the length of the stirng, or the
+ /// string can be part of another string and a new substring
+ /// can be created.
///
/// @param[in] max_cstr_len
/// The max length of \a cstr. If the string length of \a cstr
@@ -100,11 +100,8 @@
//------------------------------------------------------------------
/// Destructor
///
- /// Decrements the reference count on the contained string, and if
- /// the resulting reference count is zero, then the string is removed
- /// from the global string pool. If the reference count is still
- /// greater than zero, the string will remain in the string pool
- /// until the last reference is released by other ConstString objects.
+ /// Since constant string values are currently not reference counted,
+ /// there isn't much to do here.
//------------------------------------------------------------------
~ConstString ()
{
@@ -112,8 +109,8 @@
//----------------------------------------------------------------------
- /// C string equality function object for CStrings contains in the
- /// same StringPool only. (binary predicate).
+ /// C string equality binary predicate function object for ConstString
+ /// objects.
//----------------------------------------------------------------------
struct StringIsEqual
{
@@ -157,12 +154,7 @@
//------------------------------------------------------------------
/// Assignment operator
///
- /// Assigns the string in this object with the value from \a rhs
- /// and increments the reference count of that string.
- ///
- /// The previously contained string will be get its reference count
- /// decremented and removed from the string pool if its reference
- /// count reaches zero.
+ /// Assigns the string in this object with the value from \a rhs.
///
/// @param[in] rhs
/// Another string object to copy into this object.
@@ -182,8 +174,8 @@
///
/// Returns true if this string is equal to the string in \a rhs.
/// This operation is very fast as it results in a pointer
- /// comparison since all strings are in a uniqued and reference
- /// counted string pool.
+ /// comparison since all strings are in a uniqued in a global string
+ /// pool.
///
/// @param[in] rhs
/// Another string object to compare this object to.
@@ -205,8 +197,8 @@
///
/// Returns true if this string is not equal to the string in \a rhs.
/// This operation is very fast as it results in a pointer
- /// comparison since all strings are in a uniqued and reference
- /// counted string pool.
+ /// comparison since all strings are in a uniqued in a global string
+ /// pool.
///
/// @param[in] rhs
/// Another string object to compare this object to.
@@ -244,12 +236,32 @@
return m_string;
}
+ //------------------------------------------------------------------
+ /// Get the string value as a llvm::StringRef
+ ///
+ /// @return
+ /// Returns a new llvm::StringRef object filled in with the
+ /// needed data.
+ //------------------------------------------------------------------
llvm::StringRef
GetStringRef () const
{
return llvm::StringRef (m_string, GetLength());
}
+ //------------------------------------------------------------------
+ /// Get the string value as a C string.
+ ///
+ /// Get the value of the contained string as a NULL terminated C
+ /// string value. Similar to the ConstString::AsCString() function,
+ /// yet this function will always return NULL if the string is not
+ /// valid. So this function is a direct accessor to the string
+ /// pointer value.
+ ///
+ /// @return
+ /// Returns NULL the string is invalid, otherwise the C string
+ /// value contained in this object.
+ //------------------------------------------------------------------
const char *
GetCString () const
{
@@ -257,17 +269,24 @@
}
+ //------------------------------------------------------------------
+ /// Get the length in bytes of string value.
+ ///
+ /// The string pool stores the length of the string, so we can avoid
+ /// calling strlen() on the pointer value with this function.
+ ///
+ /// @return
+ /// Returns the number of bytes that this string occupies in
+ /// memory, not including the NULL termination byte.
+ //------------------------------------------------------------------
size_t
GetLength () const;
+
//------------------------------------------------------------------
/// Clear this object's state.
///
/// Clear any contained string and reset the value to the an empty
/// string value.
- ///
- /// The previously contained string will be get its reference count
- /// decremented and removed from the string pool if its reference
- /// count reaches zero.
//------------------------------------------------------------------
void
Clear ()
@@ -281,6 +300,11 @@
/// Compares the C string values contained in \a lhs and \a rhs and
/// returns an integer result.
///
+ /// NOTE: only call this function when you want a true string
+ /// comparision. If you want string equality use the, use the ==
+ /// operator as it is much more efficient. Also if you want string
+ /// inequality, use the != operator for the same reasons.
+ ///
/// @param[in] lhs
/// The Left Hand Side const ConstString object reference.
///
@@ -316,9 +340,6 @@
//------------------------------------------------------------------
/// Dump the object debug description to a stream.
///
- /// Dump the string value and the reference count to the stream \a
- /// s.
- ///
/// @param[in] s
/// The stream that will be used to dump the object description.
//------------------------------------------------------------------
@@ -338,7 +359,6 @@
return m_string == NULL || m_string[0] == '\0';
}
-
//------------------------------------------------------------------
/// Set the C string value.
///
@@ -346,9 +366,8 @@
/// string value in our global string pool.
///
/// If the C string already exists in the global string pool, it
- /// finds the current entry and retains an extra reference to the
- /// string in the string pool. If it doesn't exist, it is added to
- /// the string pool with a reference count of 1.
+ /// finds the current entry and returns the existing value. If it
+ /// doesn't exist, it is added to the string pool.
///
/// @param[in] cstr
/// A NULL terminated C string to add to the string pool.
@@ -356,9 +375,47 @@
void
SetCString (const char *cstr);
+ //------------------------------------------------------------------
+ /// Set the C string value and its mangled counterpart.
+ ///
+ /// Object files and debug sybmols often use mangled string to
+ /// represent the linkage name for a symbol, function or global.
+ /// The string pool can efficiently store these values and their
+ /// counterparts so when we run into another instance of a mangled
+ /// name, we can avoid calling the name demangler over and over on
+ /// the same strings and then trying to unique them.
+ ///
+ /// @param[in] demangled
+ /// The demangled C string to correlate with the \a mangled
+ /// name.
+ ///
+ /// @param[in] mangled
+ /// The already uniqued mangled ConstString to correlate the
+ /// soon to be uniqued version of \a demangled.
+ //------------------------------------------------------------------
void
- SetCStringWithMangledCounterpart (const char *demangled, const ConstString &mangled);
+ SetCStringWithMangledCounterpart (const char *demangled,
+ const ConstString &mangled);
+ //------------------------------------------------------------------
+ /// Retrieve the mangled or demangled counterpart for a mangled
+ /// or demangled ConstString.
+ ///
+ /// Object files and debug sybmols often use mangled string to
+ /// represent the linkage name for a symbol, function or global.
+ /// The string pool can efficiently store these values and their
+ /// counterparts so when we run into another instance of a mangled
+ /// name, we can avoid calling the name demangler over and over on
+ /// the same strings and then trying to unique them.
+ ///
+ /// @param[in] counterpart
+ /// A reference to a ConstString object that might get filled in
+ /// with the demangled/mangled counterpart.
+ ///
+ /// @return
+ /// /b True if \a counterpart was filled in with the counterpart
+ /// /b false otherwise.
+ //------------------------------------------------------------------
bool
GetMangledCounterpart (ConstString &counterpart) const;
@@ -369,25 +426,17 @@
/// starting at the \a cstr string value in our global string pool.
/// If trim is true, then \a cstr_len indicates a maximum length of
/// the CString and if the actual length of the string is less, then
- /// it will be trimmed. If trim is false, then this allows strings
- /// with NULL characters to be added to the string pool.
+ /// it will be trimmed.
///
/// If the C string already exists in the global string pool, it
- /// retains an extra reference to the string in the string
- /// pool. If it doesn't exist, it is added to the string pool with
- /// a reference count of 1.
+ /// finds the current entry and returns the existing value. If it
+ /// doesn't exist, it is added to the string pool.
///
/// @param[in] cstr
/// A NULL terminated C string to add to the string pool.
///
/// @param[in] cstr_len
- /// The absolute length of the C string if \a trim is false,
- /// or the maximum length of the C string if \a trim is true.
- ///
- /// @param[in] trim
- /// If \b true, trim \a cstr to it's actual length before adding
- /// it to the string pool. If \b false then cstr_len is the
- /// actual length of the C string to add.
+ /// The maximum length of the C string.
//------------------------------------------------------------------
void
SetCStringWithLength (const char *cstr, size_t cstr_len);
@@ -425,7 +474,7 @@
/// Get the size in bytes of the current global string pool.
///
/// Reports the the size in bytes of all shared C string values,
- /// containers and reference count values as a byte size for the
+ /// containers and any other values as a byte size for the
/// entire string pool.
///
/// @return
Modified: lldb/trunk/source/Core/ConstString.cpp
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/source/Core/ConstString.cpp?rev=139487&r1=139486&r2=139487&view=diff
==============================================================================
--- lldb/trunk/source/Core/ConstString.cpp (original)
+++ lldb/trunk/source/Core/ConstString.cpp Sun Sep 11 22:55:58 2011
@@ -14,21 +14,6 @@
using namespace lldb_private;
-//----------------------------------------------------------------------
-// The global string pool is implemented as a hash_map that maps
-// std::string objects to a uint32_t reference count.
-//
-// In debug builds the value that is stored in the ConstString objects is
-// a C string that is owned by one of the std::string objects in the
-// hash map. This was done for visibility purposes when debugging as
-// gcc was often generating insufficient debug info for the
-// iterator objects.
-//
-// In release builds, the value that is stored in the ConstString objects
-// is the iterator into the ConstString::HashMap. This is much faster when
-// it comes to modifying the reference count, and removing strings from
-// the pool.
-//----------------------------------------------------------------------
class Pool
{
public:
@@ -147,7 +132,7 @@
//------------------------------------------------------------------
// Return the size in bytes that this object and any items in its
- // collection of uniqued strings + reference count values takes in
+ // collection of uniqued strings + data count values takes in
// memory.
//------------------------------------------------------------------
size_t
@@ -190,34 +175,11 @@
return string_pool;
}
-//----------------------------------------------------------------------
-// Construct with C String value
-//
-// Constructs this object with a C string by looking to see if the
-// C string already exists in the global string pool. If it does
-// exist, it retains an extra reference to the string in the string
-// pool. If it doesn't exist, it is added to the string pool with
-// a reference count of 1.
-//----------------------------------------------------------------------
ConstString::ConstString (const char *cstr) :
m_string (StringPool().GetConstCString (cstr))
{
}
-//----------------------------------------------------------------------
-// Construct with C String value with max length
-//
-// Constructs this object with a C string with a length. If
-// the length of the string is greather than "cstr_len", the
-// string length will be truncated. This allows substrings to be
-// created without the need to NULL terminate the string as it
-// is passed into this function.
-//
-// If the C string already exists in the global string pool, it
-// retains an extra reference to the string in the string
-// pool. If it doesn't exist, it is added to the string pool with
-// a reference count of 1.
-//----------------------------------------------------------------------
ConstString::ConstString (const char *cstr, size_t cstr_len) :
m_string (StringPool().GetConstCStringWithLength (cstr, cstr_len))
{
@@ -240,9 +202,6 @@
return lhs_string_ref.data() == NULL;
}
-//----------------------------------------------------------------------
-// Stream the string value "str" to the stream "s"
-//----------------------------------------------------------------------
Stream&
lldb_private::operator << (Stream& s, const ConstString& str)
{
@@ -259,14 +218,6 @@
return StringPool().GetConstCStringLength (m_string);
}
-//----------------------------------------------------------------------
-// Compare two string objects.
-//
-// Returns:
-// -1 if a < b
-// 0 if a == b
-// 1 if a > b
-//----------------------------------------------------------------------
int
ConstString::Compare (const ConstString& lhs, const ConstString& rhs)
{
@@ -288,12 +239,6 @@
return -1; // LHS is NULL but RHS isn't
}
-//----------------------------------------------------------------------
-// Dump the string value to the stream "s". If the contained string
-// is empty, print "fail_value" to the stream instead. If
-// "fail_value" is NULL, then nothing will be dumped to the
-// stream.
-//----------------------------------------------------------------------
void
ConstString::Dump(Stream *s, const char *fail_value) const
{
@@ -302,9 +247,6 @@
s->PutCString (cstr);
}
-//----------------------------------------------------------------------
-// Dump extra debug information to the stream "s".
-//----------------------------------------------------------------------
void
ConstString::DumpDebug(Stream *s) const
{
@@ -315,15 +257,6 @@
s->Printf("%*p: ConstString, string = %s%s%s, length = %zu", (int)sizeof(void*) * 2, this, parens, cstr, parens, cstr_len);
}
-//----------------------------------------------------------------------
-// Set the string value in the object by uniquing the "cstr" string
-// value in our global string pool.
-//
-// If the C string already exists in the global string pool, it
-// retains an extra reference to the string in the string
-// pool. If it doesn't exist, it is added to the string pool with
-// a reference count of 1.
-//----------------------------------------------------------------------
void
ConstString::SetCString (const char *cstr)
{
@@ -343,19 +276,6 @@
return counterpart;
}
-//----------------------------------------------------------------------
-// Set the string value in the object by uniquing "cstr_len" bytes
-// starting at the "cstr" string value in our global string pool.
-// If trim is true, then "cstr_len" indicates a maximum length of
-// the CString and if the actual length of the string is less, then
-// it will be trimmed. If trim is false, then this allows strings
-// with NULL characters ('\0') to be added to the string pool.
-//
-// If the C string already exists in the global string pool, it
-// retains an extra reference to the string in the string
-// pool. If it doesn't exist, it is added to the string pool with
-// a reference count of 1.
-//----------------------------------------------------------------------
void
ConstString::SetCStringWithLength (const char *cstr, size_t cstr_len)
{
@@ -368,11 +288,6 @@
m_string = StringPool().GetConstTrimmedCStringWithLength (cstr, cstr_len);
}
-//----------------------------------------------------------------------
-// Reports the the size in bytes of all shared C string values,
-// containers and reference count values as a byte size for the
-// entire string pool.
-//----------------------------------------------------------------------
size_t
ConstString::StaticMemorySize()
{
More information about the lldb-commits
mailing list