API for xSemaphoreGetMutexHolder

amomum wrote on Friday, June 19, 2015:

There is an API function xSemaphoreGetMutexHolder. For some reason, on the API page http://www.freertos.org/xSemaphoreGetMutexHolder.html return type is missing.

So I looked in the source code and saw that xSemaphoreGetMutexHolder is actually a macro for xQueueGetMutexHolder. And xQueueGetMutexHolder returns “void *” although it’s prefix (x) should mean something else.

I’m not entirely sure what does x-prefix mean but every other functions that return “void *” are prefixed with “pv”.

After reading API reference I figured out that it actually should return TaskHandle_t (which is a typedef for void *).

Although this is not a bug I’m not sure it’s as it should be.


Return type is also missing in API references for xSemaphoreTake, xSemaphoreTakeFromISR, xSemaphoreTakeRecursive, xSemaphoreGive, xSemaphoreGiveRecursive and xSemaphoreGiveFromISR.

rtel wrote on Friday, June 19, 2015:

Thanks for pointing out the missing return type 
in the documentation - it has been corrected.

I suspect the function returns a void* because 
inside the queue.c the TaskHandle_t type is not 
known - and it can't be relied upon that an 
application writer will include task.h before 
queue.h.  Returning void* is ok as it can be cast 
to any type, and in this case TaskHandle_t is itself 
a void * - hence I have updated the documentation to 
show a TaskHandle_t being returned.


[edited to remove formatting as the forum uses the asterisk as a formatting character.]

amomum wrote on Friday, June 19, 2015:

I presume, including task.h inside queue.h is not acceptable? Then, I guess, it’s okay.

As far as I can see, you didn’t update API references for other functions that I mentioned.