1 files changed, 25 insertions, 16 deletions

diff --git a/python/google/protobuf/internal/message_listener.py b/python/google/protobuf/internal/message_listener.py
index 4397895..1080234 100755
--- a/python/google/protobuf/internal/message_listener.py
+++ b/python/google/protobuf/internal/message_listener.py
@@ -39,22 +39,34 @@ __author__ = 'robinson@google.com (Will Robinson)'
 
 class MessageListener(object):
 
-  """Listens for transitions to nonempty and for invalidations of cached
-  byte sizes.  Meant to be registered via Message._SetListener().
+  """Listens for modifications made to a message.  Meant to be registered via
+  Message._SetListener().
+
+  Attributes:
+    dirty:  If True, then calling Modified() would be a no-op.  This can be
+            used to avoid these calls entirely in the common case.
   """
 
-  def TransitionToNonempty(self):
-    """Called the *first* time that this message becomes nonempty.
-    Implementations are free (but not required) to call this method multiple
-    times after the message has become nonempty.
-    """
-    raise NotImplementedError
+  def Modified(self):
+    """Called every time the message is modified in such a way that the parent
+    message may need to be updated.  This currently means either:
+    (a) The message was modified for the first time, so the parent message
+        should henceforth mark the message as present.
+    (b) The message's cached byte size became dirty -- i.e. the message was
+        modified for the first time after a previous call to ByteSize().
+        Therefore the parent should also mark its byte size as dirty.
+    Note that (a) implies (b), since new objects start out with a client cached
+    size (zero).  However, we document (a) explicitly because it is important.
+
+    Modified() will *only* be called in response to one of these two events --
+    not every time the sub-message is modified.
 
-  def ByteSizeDirty(self):
-    """Called *every* time the cached byte size value
-    for this object is invalidated (transitions from being
-    "clean" to "dirty").
+    Note that if the listener's |dirty| attribute is true, then calling
+    Modified at the moment would be a no-op, so it can be skipped.  Performance-
+    sensitive callers should check this attribute directly before calling since
+    it will be true most of the time.
     """
+
     raise NotImplementedError
 
 
@@ -62,8 +74,5 @@ class NullMessageListener(object):
 
   """No-op MessageListener implementation."""
 
-  def TransitionToNonempty(self):
-    pass
-
-  def ByteSizeDirty(self):
+  def Modified(self):
     pass