Update ValidationInterface() documentation to explicitly specify threading and memory model

skeees · furszy · commit f9d2ab3f3f0c · 2021-04-03T10:01:36.000-03:00
diff --git a/src/validationinterface.h b/src/validationinterface.h
@@ -54,6 +54,21 @@ void CallFunctionInValidationInterfaceQueue(std::function<void ()> func);
  */
 void SyncWithValidationInterfaceQueue();
 
+/**
+ * Implement this to subscribe to events generated in validation
+ *
+ * Each CValidationInterface() subscriber will receive event callbacks
+ * in the order in which the events were generated by validation.
+ * Furthermore, each ValidationInterface() subscriber may assume that
+ * callbacks effectively run in a single thread with single-threaded
+ * memory consistency. That is, for a given ValidationInterface()
+ * instantiation, each callback will complete before the next one is
+ * invoked. This means, for example when a block is connected that the
+ * UpdatedBlockTip() callback may depend on an operation performed in
+ * the BlockConnected() callback without worrying about explicit
+ * synchronization. No ordering should be assumed across
+ * ValidationInterface() subscribers.
+ */
 class CValidationInterface {
 public:
     virtual ~CValidationInterface() = default;
