# HG changeset patch
# User Martin von Zweigbergk <martinvonz@google.com>
# Date 2019-06-26 12:20:02
# Node ID 898b36f74f7537522663c40d9cb24869a8423247
# Parent  907cef3966354ec4b6f6583b3803b02e44c35675

copies: document how 'copies' dict instances are reused

We avoid copying these instances as much as we can, so it's not
obvious what's safe to do with them. This patch tries to explain what
is safe and what is not.

Differential Revision: https://phab.mercurial-scm.org/D6578

diff --git a/mercurial/copies.py b/mercurial/copies.py
--- a/mercurial/copies.py
+++ b/mercurial/copies.py
@@ -268,6 +268,10 @@ def _changesetforwardcopies(a, b, match)
     # 'work' contains 3-tuples of a (revision number, parent number, copies).
     # The parent number is only used for knowing which parent the copies dict
     # came from.
+    # NOTE: To reduce costly copying the 'copies' dicts, we reuse the same
+    # instance for *one* of the child nodes (the last one). Once an instance
+    # has been put on the queue, it is thus no longer safe to modify it.
+    # Conversely, it *is* safe to modify an instance popped off the queue.
     work = [(r, 1, {}) for r in roots]
     heapq.heapify(work)
     alwaysmatch = match.always()