From: Gabriel Kerneis <gabr...@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 <gabr...@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 e11a587..02ce32d 100644
--- a/include/block/coroutine.h
+++ b/include/block/coroutine.h
@@ -54,6 +54,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.8.4.rc3
