CHRE API: Allow exception to non-reentrant rulenougat-mr1-dev

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

2 files changed, 15 insertions, 6 deletions

diff --git a/inc/chre.h b/inc/chre.h
index 3cad8930..950f03c7 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 465c40ac..c1c95108 100644
--- a/inc/chre_event.h
+++ b/inc/chre_event.h
@@ -202,7 +202,9 @@ typedef void (chreMessageFreeFunction)(void *message, size_t messageSize);
  *     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 @@ bool chreSendEvent(uint16_t eventType, void *eventData,
  *     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
  */