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.

UPD:

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.

Regards.

[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.