Understanding the fine difference between ulBitsToClearOnEntry and ulBitsToClearOnExit in xTaskNotifyWait()

I have been trying to play with Task Notifications but I am stuck understanding the difference between ulBitsToClearOnEntry and ulBitsToClearOnExit in xTaskNotifyWait().

The documentation states otherwise but my implementation somehow seem to be doing the task of resetting the bit specified and I am not able to think of an application which makes the difference between the two, obvious.

One common use of the notification bits is to represent recent events that need your attention, where each bit represents a different event. You can think of the decision about when to clear bits as what you want to tell FreeRTOS about events that happen in between calls to the wait API functions.

If you clear a bit on entry, then you’re telling FreeRTOS you don’t care about any instances of the event that happened since the last call to the API function. The only way that bit will be set when the API function returns is if the event happens while the API function is executing or waiting.

If you clear a bit on exit, you’re telling FreeRTOS that you want to know about any instances of the event that occur, even if they occur while your code has control and is actively processing events.

If you pass zero for both parameters, then those bits will never be cleared (unless you call other API functions that manipulate the notification value). Even without ever clearing the bits, the API functions will still wait for the events that set the bits because the API functions wait for the notification state, not the notification value.


I was confused at first, reading your reply and so, I went through the implementation. I now understand your explanation.

But documentation says:
Any bits set in ulBitsToClearOnEntry will be cleared in the calling RTOS task’s notification value on entry to the xTaskNotifyWait() function (before the task waits for a new notification) provided a notification is not already pending when xTaskNotifyWait() is called.
So it seems to me,that if some event happened during processing the task handler, ulBitsToClear OnEntry will not be applied xTaskNotifyWait will not block and task handler continues processing new events?

Yes, that is correct. You can see that the bits are cleared here and that happens only when a notification is not pending.

then it seems to me that the explanation/solution is not valid and the usage of ulBitsToClearOn… remains mysterious.

@Ondrej_Pokorny You are right and thank you for identifying the discrepancy. The answer I gave above is not correct.

If we are still talking about using task notifications as a light weight event group as I described above, then the purpose of ulBitsToClearOnExit still seems clear. That’s how you clear events, just before your application processes them.

But I suspect there’s really not much use for ulBitsToClearOnEntry when using task notifications to track events.

Hello Jeff,
in discussion with our team we came to the same result.
Thank You.