[llvm] 4f16ccd - [JITLink] Clarify LinkGraph::splitBlock contract in comment.

[Lang Hames via llvm-commits]

Author: Lang Hames
Date: 2021-06-08T18:51:12+10:00
New Revision: 4f16ccdab2d39ed1fb718ce646507c07b6c2de46

URL: https://github.com/llvm/llvm-project/commit/4f16ccdab2d39ed1fb718ce646507c07b6c2de46
DIFF: https://github.com/llvm/llvm-project/commit/4f16ccdab2d39ed1fb718ce646507c07b6c2de46.diff

LOG: [JITLink] Clarify LinkGraph::splitBlock contract in comment.

Added: 
    

Modified: 
    llvm/include/llvm/ExecutionEngine/JITLink/JITLink.h

Removed: 
    


################################################################################
diff  --git a/llvm/include/llvm/ExecutionEngine/JITLink/JITLink.h b/llvm/include/llvm/ExecutionEngine/JITLink/JITLink.h
index 7d626e3c9db8c..15b5286b869a6 100644
--- a/llvm/include/llvm/ExecutionEngine/JITLink/JITLink.h
+++ b/llvm/include/llvm/ExecutionEngine/JITLink/JITLink.h
@@ -991,12 +991,21 @@ class LinkGraph {
   ///
   /// Notes:
   ///
-  /// 1. The newly introduced block will have a new ordinal which will be
+  /// 1. splitBlock must be used with care. Splitting a block may cause
+  ///    incoming edges to become invalid if the edge target subexpression
+  ///    points outside the bounds of the newly split target block (E.g. an
+  ///    edge 'S + 10 : Pointer64' where S points to a newly split block
+  ///    whose size is less than 10). No attempt is made to detect invalidation
+  ///    of incoming edges, as in general this requires context that the
+  ///    LinkGraph does not have. Clients are responsible for ensuring that
+  ///    splitBlock is not used in a way that invalidates edges.
+  ///
+  /// 2. The newly introduced block will have a new ordinal which will be
   ///    higher than any other ordinals in the section. Clients are responsible
   ///    for re-assigning block ordinals to restore a compatible order if
   ///    needed.
   ///
-  /// 2. The cache is not automatically updated if new symbols are introduced
+  /// 3. The cache is not automatically updated if new symbols are introduced
   ///    between calls to splitBlock. Any newly introduced symbols may be
   ///    added to the cache manually (descending offset order must be
   ///    preserved), or the cache can be set to None and rebuilt by