[Qemu-devel] [RFC] Introduce blocking_fn annotation

[Gabriel Kerneis <gabriel@kerneis.info>]

A blocking function is a function that must not be called in coroutine
context, for example because it might block for a long amount of time.
This annotation should be used to mark normal functions that have a
coroutine_fn counterpart, to make sure that the former is not used
instead of the later in coroutine context.

Signed-off-by: Gabriel Kerneis <gabriel@kerneis.info>
---
 include/block/coroutine.h |   23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/include/block/coroutine.h b/include/block/coroutine.h
index 4232569..a92d14f 100644
--- a/include/block/coroutine.h
+++ b/include/block/coroutine.h
@@ -46,6 +46,29 @@
  */
 #define coroutine_fn
 
+/**
+ * Mark a function that executes in blocking context
+ *
+ * Functions that execute in blocking context cannot be called directly from
+ * coroutine functions.  In the future it would be nice to enable compiler or
+ * static checker support for catching such errors.  This annotation might make
+ * it possible and in the meantime it serves as documentation.
+ *
+ * Annotating a function as "blocking" is stronger than having a mere
+ * (unannotated) normal function. It means that it might block the main
+ * loop for a significant amount of time, and therefore must not be
+ * called in coroutine context. In general, its hints that an
+ * alternative coroutine function performing the same taks is available
+ * for use in coroutine context.
+ *
+ * For example:
+ *
+ *   static void blocking_fn foo(void) {
+ *       ....
+ *   }
+ */
+#define blocking_fn
+
 typedef struct Coroutine Coroutine;
 
 /**
-- 
1.7.10.4