[ObjC] Update comments about common failure causes.

PiperOrigin-RevId: 509914968

objectivec/GPBMessage.h

@@ -293,6 +293,10 @@ CF_EXTERN_C_END
  *
  * @note This can raise the GPBCodedOutputStreamException_* exceptions.
  *
+ * @note The most common cause of this failing is from one thread calling this
+ *       while another thread has a reference to this message or a message used
+ *       within a field and that other thread mutating the message while this
+ *       serialization is taking place.
  **/
 - (void)writeToCodedOutputStream:(GPBCodedOutputStream *)output;
 
@@ -302,6 +306,11 @@ CF_EXTERN_C_END
  * @param output The output stream into which to write the message.
  *
  * @note This can raise the GPBCodedOutputStreamException_* exceptions.
+ *
+ * @note The most common cause of this failing is from one thread calling this
+ *       while another thread has a reference to this message or a message used
+ *       within a field and that other thread mutating the message while this
+ *       serialization is taking place.
  **/
 - (void)writeToOutputStream:(NSOutputStream *)output;
 
@@ -312,6 +321,11 @@ CF_EXTERN_C_END
  * @param output The coded output stream into which to write the message.
  *
  * @note This can raise the GPBCodedOutputStreamException_* exceptions.
+ *
+ * @note The most common cause of this failing is from one thread calling this
+ *       while another thread has a reference to this message or a message used
+ *       within a field and that other thread mutating the message while this
+ *       serialization is taking place.
  **/
 - (void)writeDelimitedToCodedOutputStream:(GPBCodedOutputStream *)output;
 
@@ -322,6 +336,11 @@ CF_EXTERN_C_END
  * @param output The output stream into which to write the message.
  *
  * @note This can raise the GPBCodedOutputStreamException_* exceptions.
+ *
+ * @note The most common cause of this failing is from one thread calling this
+ *       while another thread has a reference to this message or a message used
+ *       within a field and that other thread mutating the message while this
+ *       serialization is taking place.
  **/
 - (void)writeDelimitedToOutputStream:(NSOutputStream *)output;
 
@@ -336,6 +355,11 @@ CF_EXTERN_C_END
  * @note In DEBUG ONLY, the message is also checked for all required field,
  *       if one is missing, nil will be returned.
  *
+ * @note The most common cause of this failing is from one thread calling this
+ *       while another thread has a reference to this message or a message used
+ *       within a field and that other thread mutating the message while this
+ *       serialization is taking place.
+ *
  * @return The binary representation of the message.
  **/
 - (nullable NSData *)data;
@@ -347,6 +371,11 @@ CF_EXTERN_C_END
  * @note This value is not cached, so if you are using it repeatedly, it is
  *       recommended to keep a local copy.
  *
+ * @note The most common cause of this failing is from one thread calling this
+ *       while another thread has a reference to this message or a message used
+ *       within a field and that other thread mutating the message while this
+ *       serialization is taking place.
+ *
  * @return The binary representation of the size along with the message.
  **/
 - (NSData *)delimitedData;

objectivec/GPBMessage.m

@@ -1308,9 +1308,12 @@ - (NSData *)data {
   @try {
     [self writeToCodedOutputStream:stream];
   } @catch (NSException *exception) {
-    // This really shouldn't happen. The only way writeToCodedOutputStream:
-    // could throw is if something in the library has a bug and the
-    // serializedSize was wrong.
+    // This really shouldn't happen. Normally, this could mean there was a bug in the library and it
+    // failed to match between computing the size and writing out the bytes. However, the more
+    // common cause is while one thread was writing out the data, some other thread had a reference
+    // to this message or a message used as a nested field, and that other thread mutated that
+    // message, causing the pre computed serializedSize to no longer match the final size after
+    // serialization. It is not safe to mutate a message while accessing it from another thread.
 #ifdef DEBUG
     NSLog(@"%@: Internal exception while building message data: %@", [self class], exception);
 #endif
@@ -1328,9 +1331,12 @@ - (NSData *)delimitedData {
   @try {
     [self writeDelimitedToCodedOutputStream:stream];
   } @catch (NSException *exception) {
-    // This really shouldn't happen.  The only way writeToCodedOutputStream:
-    // could throw is if something in the library has a bug and the
-    // serializedSize was wrong.
+    // This really shouldn't happen. Normally, this could mean there was a bug in the library and it
+    // failed to match between computing the size and writing out the bytes. However, the more
+    // common cause is while one thread was writing out the data, some other thread had a reference
+    // to this message or a message used as a nested field, and that other thread mutated that
+    // message, causing the pre computed serializedSize to no longer match the final size after
+    // serialization. It is not safe to mutate a message while accessing it from another thread.
 #ifdef DEBUG
     NSLog(@"%@: Internal exception while building message delimitedData: %@", [self class],
           exception);