CHRE API: Allow inline freeing of message data
The documentation currently allows for chreSendMessageToHost() to invoke
the message free callback directly in failure cases. Extend this to
successful cases as well, to allow for CHRE implementations where the
nanoapp-supplied message buffer is consumed synchronously.
Bug: 32795182
Test: none, this is a comment-only change
Change-Id: Ie3a74ccad557042b698b0899b08e3b005e5041c3
diff --git a/inc/chre.h b/inc/chre.h
index 2587e3d..5f45498 100644
--- a/inc/chre.h
+++ b/inc/chre.h
@@ -73,15 +73,19 @@
* callback, the CHRE is not allowed to call nanoappHandleEvent(), or invoke
* another memory freeing callback.
*
- * 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.
+ * There are two exceptions to this rule: If an invocation of chreSendEvent()
+ * 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. Similarly,
+ * chreSendMessageToHost() is allowed to invoke the memory freeing callback
+ * directly, whether it returns 'true' or 'false'. This is because the CHRE
+ * implementation may copy the message data to its own buffer, and therefore
+ * wouldn't need the nanoapp-supplied buffer after chreSendMessageToHost()
+ * returns.
*
- * 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.
+ * 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.
*
*
* [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 c1c9510..0f088bb 100644
--- a/inc/chre/event.h
+++ b/inc/chre/event.h
@@ -254,9 +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. 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.
+ * be invoked, if non-NULL. In either 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
*/
