CHRE API: Allow exception to non-reentrant rule
Per discussion, we've concluded it's best to allow a CHRE
implementation to have one exception to the non-reentrant
rule. We update the documentation to reflect this
decision.
Bug: 31959429
Change-Id: Ibc7a1393812d975f8d9965d68f182a34f1e9024f
diff --git a/inc/chre.h b/inc/chre.h
index 3cad893..950f03c 100644
--- a/inc/chre.h
+++ b/inc/chre.h
@@ -73,9 +73,15 @@
* callback, the CHRE is not allowed to call nanoappHandleEvent(), or invoke
* another memory freeing callback.
*
- * For a nanoapp author, this means no thought needs to be given to
- * synchronization issues with global objects, as they will, by definition,
- * only be accessed by a single thread at once.
+ * There is one exception to this rule: If an invocation of chreSendEvent()
+ * or chreSendMessageToHost() fails (returns 'false'), it is allowed to
+ * immediately invoke the memory freeing callback passed into that function.
+ * This is a rare case, and one where otherwise a CHRE implementation is
+ * likely to leak memory.
+ *
+ * For a nanoapp author, this means no thought (outside of our one exception)
+ * needs to be given to synchronization issues with global objects, as they
+ * will, by definition, only be accessed by a single thread at once.
*
*
* [1] Note to CHRE implementors: A future version of the CHRE platform may
diff --git a/inc/chre_event.h b/inc/chre_event.h
index 465c40a..c1c9510 100644
--- a/inc/chre_event.h
+++ b/inc/chre_event.h
@@ -202,7 +202,9 @@
* to. Note that this is allowed to be our own instance.
* @returns true if the event was enqueued, false otherwise. Note that even
* if this method returns 'false', the 'freeCallback' will be invoked,
- * if non-NULL.
+ * if non-NULL. Note in the 'false' case, the 'freeCallback' may be
+ * invoked directly from within chreSendEvent(), so it's necessary
+ * for nanoapp authors to avoid possible recursion with this.
*
* @see chreEventDataFreeFunction
*/
@@ -252,8 +254,9 @@
* to be NULL, in which case no callback will be invoked.
* @returns true if the message was accepted for transmission, false otherwise.
* Note that even if this method returns 'false', the 'freeCallback' will
- * be invoked, if non-NULL.
- *
+ * be invoked, if non-NULL. Note in the 'false' case, the 'freeCallback'
+ * may be invoked directly from within chreSendMessageToHost(), so it's
+ * necessary for nanoapp authors to avoid possible recursion with this.
*
* @see chreMessageFreeFunction
*/
