improve mutex doc #8391
improve mutex doc #8391
Conversation
rtos/Mutex.h
Outdated
| @@ -82,7 +82,7 @@ class Mutex : private mbed::NonCopyable<Mutex> { | |||
| Wait until a Mutex becomes available. | |||
|
|
|||
| @return status code that indicates the execution status of the function: | |||
| @a osOK the mutex has been obtained. | |||
| @a Status code like osOK indicates that the mutex has been obtained. | |||
There was a problem hiding this comment.
"Like" means similar to but not including. "Such as" means similar to and including. So if osOK is a status code that indicates that the mutex has been obtained, please change "like" to "such as". If osOK is similar to status code that indicates that the mutex has been obtained but isn't that, please leave as is.
rtos/Mutex.h
Outdated
| @@ -144,7 +144,7 @@ class Mutex : private mbed::NonCopyable<Mutex> { | |||
| Unlock the mutex that has previously been locked by the same thread | |||
|
|
|||
| @return status code that indicates the execution status of the function: | |||
| @a osOK the mutex has been released. | |||
| @a Status code like osOK indicates that the mutex has been released. | |||
There was a problem hiding this comment.
Please see earlier comment.
|
Modified |
rtos/Mutex.h
Outdated
| @@ -82,7 +82,7 @@ class Mutex : private mbed::NonCopyable<Mutex> { | |||
| Wait until a Mutex becomes available. | |||
|
|
|||
| @return status code that indicates the execution status of the function: | |||
| @a osOK the mutex has been obtained. | |||
| @a Status code such as osOK indicates that the mutex has been obtained. | |||
There was a problem hiding this comment.
No, the only thing this can return is osOK. See the note below. Same for the other function
Make minor copy edits to existing text.
|
|
||
| @note You cannot use member functions of this class in ISR context. If you require Mutex functionality within | ||
| ISR handler, consider using @a Semaphore. | ||
|
|
||
| @note | ||
| Memory considerations: The mutex control structures will be created on current thread's stack, both for the Mbed OS | ||
| Memory considerations: The mutex control structures are created on the current thread's stack, both for the Mbed OS |
There was a problem hiding this comment.
Wouldn't have noticed this note apart from the edit, but it's false.
The RTOS mutex control structure is embedded in the Mutex object itself (rather than any RTOS memory pool), so the allocation is determined by where you allocate the Mutex. That could conceivably be on the stack, but not in any normal application.
There was a problem hiding this comment.
There was a problem hiding this comment.
Sorry I was not in office for couple of days. We would need to file separate PR for it since this is already merged. @kjbracey-arm , would you please file a PR with the accurate description? Thanks
Description
Improve documentation for mutex