Bug 1407858 part 1. Give DOMString setter APIs clearer names. r=smaug

The renaming here is like this:

  SetStringBuffer -> SetKnownLiveStringBuffer
  SetEphemeralStringBuffer -> SetStringBuffer
  SetOwnedString -> SetKnownLiveString
  SetOwnedAtom -> SetKnownLiveAtom

This should make it clearer what the lifetime expectations are on the caller side.

MozReview-Commit-ID: ERHbB3r6paN

dom/base/nsAttrValueInlines.h

@@ -270,7 +270,8 @@ nsAttrValue::ToString(mozilla::dom::DOMString& aResult) const
     {
       nsStringBuffer* str = static_cast<nsStringBuffer*>(GetPtr());
       if (str) {
-        aResult.SetStringBuffer(str, str->StorageSize()/sizeof(char16_t) - 1);
+        aResult.SetKnownLiveStringBuffer(
+          str, str->StorageSize()/sizeof(char16_t) - 1);
       }
       // else aResult is already empty
       return;
@@ -278,7 +279,7 @@ nsAttrValue::ToString(mozilla::dom::DOMString& aResult) const
     case eAtom:
     {
       nsAtom *atom = static_cast<nsAtom*>(GetPtr());
-      aResult.SetOwnedAtom(atom, mozilla::dom::DOMString::eNullNotExpected);
+      aResult.SetKnownLiveAtom(atom, mozilla::dom::DOMString::eNullNotExpected);
       break;
     }
     default:

dom/base/nsDOMMutationObserver.h

@@ -59,7 +59,7 @@ public:
 
   void GetType(mozilla::dom::DOMString& aRetVal) const
   {
-    aRetVal.SetOwnedAtom(mType, mozilla::dom::DOMString::eNullNotExpected);
+    aRetVal.SetKnownLiveAtom(mType, mozilla::dom::DOMString::eNullNotExpected);
   }
 
   nsINode* GetTarget() const
@@ -83,17 +83,18 @@ public:
 
   void GetAttributeName(mozilla::dom::DOMString& aRetVal) const
   {
-    aRetVal.SetOwnedAtom(mAttrName, mozilla::dom::DOMString::eTreatNullAsNull);
+    aRetVal.SetKnownLiveAtom(mAttrName,
+                             mozilla::dom::DOMString::eTreatNullAsNull);
   }
 
   void GetAttributeNamespace(mozilla::dom::DOMString& aRetVal) const
   {
-    aRetVal.SetOwnedString(mAttrNamespace);
+    aRetVal.SetKnownLiveString(mAttrNamespace);
   }
 
   void GetOldValue(mozilla::dom::DOMString& aRetVal) const
   {
-    aRetVal.SetOwnedString(mPrevValue);
+    aRetVal.SetKnownLiveString(mPrevValue);
   }
 
   void GetAddedAnimations(AnimationArray& aRetVal) const

dom/base/nsINode.h

@@ -1818,7 +1818,7 @@ public:
   void GetNodeName(mozilla::dom::DOMString& aNodeName)
   {
     const nsString& nodeName = NodeName();
-    aNodeName.SetOwnedString(nodeName);
+    aNodeName.SetKnownLiveString(nodeName);
   }
   MOZ_MUST_USE nsresult GetBaseURI(nsAString& aBaseURI) const;
   // Return the base URI for the document.
@@ -1882,7 +1882,7 @@ public:
   void GetLocalName(mozilla::dom::DOMString& aLocalName) const
   {
     const nsString& localName = LocalName();
-    aLocalName.SetOwnedString(localName);
+    aLocalName.SetKnownLiveString(localName);
   }
 
   nsDOMAttributeMap* GetAttributes();

dom/bindings/DOMString.h

@@ -22,21 +22,21 @@ namespace dom {
  * A class for representing string return values.  This can be either passed to
  * callees that have an nsString or nsAString out param or passed to a callee
  * that actually knows about this class and can work with it.  Such a callee may
- * call SetStringBuffer or SetEphemeralStringBuffer or SetOwnedString or
- * SetOwnedAtom on this object.  It's only OK to call
- * SetStringBuffer/SetOwnedString/SetOwnedAtom if the caller of the method in
- * question plans to keep holding a strong ref to the stringbuffer involved,
- * whether it's a raw nsStringBuffer, or stored inside the string or atom being
- * passed.  In the string/atom cases that means the caller must own the string
- * or atom, and not mutate it (in the string case) for the lifetime of the
- * DOMString.
+ * call SetKnownLiveStringBuffer or SetStringBuffer or SetKnownLiveString or
+ * SetKnownLiveAtom on this object.  It's only OK to call
+ * SetKnownLiveStringBuffer/SetKnownLiveString/SetKnownLiveAtom if the caller of
+ * the method in question plans to keep holding a strong ref to the stringbuffer
+ * involved, whether it's a raw nsStringBuffer, or stored inside the string or
+ * atom being passed.  In the string/atom cases that means the caller must own
+ * the string or atom, and not mutate it (in the string case) for the lifetime
+ * of the DOMString.
  *
  * The proper way to store a value in this class is to either to do nothing
  * (which leaves this as an empty string), to call
- * SetStringBuffer/SetEphemeralStringBuffer with a non-null stringbuffer, to
- * call SetOwnedString, to call SetOwnedAtom, to call SetNull(), or to call
- * AsAString() and set the value in the resulting nsString.  These options are
- * mutually exclusive! Don't do more than one of them.
+ * SetKnownLiveStringBuffer/SetStringBuffer with a non-null stringbuffer, to
+ * call SetKnownLiveString, to call SetKnownLiveAtom, to call SetNull(), or to
+ * call AsAString() and set the value in the resulting nsString.  These options
+ * are mutually exclusive! Don't do more than one of them.
  *
  * The proper way to extract a value is to check IsNull().  If not null, then
  * check HasStringBuffer().  If that's true, check for a zero length, and if the
@@ -131,7 +131,7 @@ public:
   // Initialize the DOMString to a (nsStringBuffer, length) pair.  The length
   // does NOT have to be the full length of the (null-terminated) string in the
   // nsStringBuffer.
-  void SetStringBuffer(nsStringBuffer* aStringBuffer, uint32_t aLength)
+  void SetKnownLiveStringBuffer(nsStringBuffer* aStringBuffer, uint32_t aLength)
   {
     MOZ_ASSERT(mString.isNothing(), "We already have a string?");
     MOZ_ASSERT(!mIsNull, "We're already set as null");
@@ -141,23 +141,23 @@ public:
     mLength = aLength;
   }
 
-  // Like SetStringBuffer, but holds a reference to the nsStringBuffer.
-  void SetEphemeralStringBuffer(nsStringBuffer* aStringBuffer, uint32_t aLength)
+  // Like SetKnownLiveStringBuffer, but holds a reference to the nsStringBuffer.
+  void SetStringBuffer(nsStringBuffer* aStringBuffer, uint32_t aLength)
   {
-    // We rely on SetStringBuffer to ensure our state invariants.
-    SetStringBuffer(aStringBuffer, aLength);
+    // We rely on SetKnownLiveStringBuffer to ensure our state invariants.
+    SetKnownLiveStringBuffer(aStringBuffer, aLength);
     aStringBuffer->AddRef();
     mStringBufferOwned = true;
   }
 
-  void SetOwnedString(const nsAString& aString)
+  void SetKnownLiveString(const nsAString& aString)
   {
     MOZ_ASSERT(mString.isNothing(), "We already have a string?");
     MOZ_ASSERT(!mIsNull, "We're already set as null");
     MOZ_ASSERT(!mStringBuffer, "Setting stringbuffer twice?");
     nsStringBuffer* buf = nsStringBuffer::FromString(aString);
     if (buf) {
-      SetStringBuffer(buf, aString.Length());
+      SetKnownLiveStringBuffer(buf, aString.Length());
     } else if (aString.IsVoid()) {
       SetNull();
     } else if (!aString.IsEmpty()) {
@@ -172,7 +172,7 @@ public:
     eNullNotExpected
   };
 
-  void SetOwnedAtom(nsAtom* aAtom, NullHandling aNullHandling)
+  void SetKnownLiveAtom(nsAtom* aAtom, NullHandling aNullHandling)
   {
     MOZ_ASSERT(mString.isNothing(), "We already have a string?");
     MOZ_ASSERT(!mIsNull, "We're already set as null");
@@ -185,7 +185,7 @@ public:
         AsAString().AssignLiteral(aAtom->GetUTF16String(), aAtom->GetLength());
       } else {
         // Dynamic atoms always have a string buffer.
-        SetStringBuffer(aAtom->GetStringBuffer(), aAtom->GetLength());
+        SetKnownLiveStringBuffer(aAtom->GetStringBuffer(), aAtom->GetLength());
       }
     } else if (aNullHandling == eTreatNullAsNull) {
       SetNull();

dom/bindings/test/TestFunctions.cpp

@@ -75,7 +75,7 @@ TestFunctions::GetStringDataAsDOMString(const Optional<uint32_t>& aLength,
 
   nsStringBuffer* buf = nsStringBuffer::FromString(mStringData);
   if (buf) {
-    aString.SetStringBuffer(buf, length);
+    aString.SetKnownLiveStringBuffer(buf, length);
     return;
   }
 

dom/xhr/XMLHttpRequestString.cpp

@@ -70,10 +70,10 @@ public:
     //      DOMString.
     nsStringBuffer* buf = nsStringBuffer::FromString(mData);
     if (buf) {
-      // We have to use SetEphemeralStringBuffer, because once we release our
-      // mutex mData can get mutated from some other thread while the DOMString
-      // is still alive.
-      aString.SetEphemeralStringBuffer(buf, aLength);
+      // We have to use SetStringBuffer, because once we release our mutex mData
+      // can get mutated from some other thread while the DOMString is still
+      // alive.
+      aString.SetStringBuffer(buf, aLength);
       return true;
     }
 

layout/style/CSSNamespaceRule.h

@@ -40,7 +40,7 @@ public:
     GetURLSpec(aNamespaceURI);
   }
   void GetPrefix(DOMString& aPrefix) {
-    aPrefix.SetOwnedAtom(GetPrefix(), DOMString::eTreatNullAsEmpty);
+    aPrefix.SetKnownLiveAtom(GetPrefix(), DOMString::eTreatNullAsEmpty);
   }
 
   size_t SizeOfIncludingThis(MallocSizeOf aMallocSizeOf) const = 0;