From 964a25f657a1c450ab07c1c3be8b9d9b1637d441 Mon Sep 17 00:00:00 2001 From: Greg Kaiser Date: Tue, 11 Oct 2016 21:06:33 -0700 Subject: 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 --- inc/chre.h | 12 +++++++++--- inc/chre_event.h | 9 ++++++--- 2 files changed, 15 insertions(+), 6 deletions(-) (limited to 'inc') 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 */ -- cgit v1.2.3