New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

improve mutex doc #8391

Merged
merged 4 commits into from Oct 13, 2018

Conversation

Projects
None yet
5 participants
@aashishc1988
Contributor

aashishc1988 commented Oct 11, 2018

Description

Improve documentation for mutex

[ ] Fix
[x ] Refactor
[ ] Target update
[ ] Functionality change
[ ] Breaking change
@aashishc1988

This comment has been minimized.

Contributor

aashishc1988 commented Oct 11, 2018

@0xc0170 0xc0170 requested a review from AnotherButler Oct 11, 2018

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

This comment has been minimized.

@AnotherButler

AnotherButler Oct 11, 2018

Contributor

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

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

This comment has been minimized.

@AnotherButler

AnotherButler Oct 11, 2018

Contributor

Please see earlier comment.

@aashishc1988

This comment has been minimized.

Contributor

aashishc1988 commented Oct 11, 2018

Modified

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

This comment has been minimized.

@kjbracey-arm

kjbracey-arm Oct 12, 2018

Contributor

No, the only thing this can return is osOK. See the note below. Same for the other function

This comment has been minimized.

@cmonr

This comment has been minimized.

@aashishc1988

aashishc1988 Oct 12, 2018

Contributor

addressed

@cmonr cmonr added needs: work and removed needs: review labels Oct 12, 2018

aashishc1988 and others added some commits Oct 12, 2018

Edit Mutex.h
Make minor copy edits to existing text.

@cmonr cmonr merged commit bbc6e5d into ARMmbed:master Oct 13, 2018

11 checks passed

continuous-integration/jenkins/pr-head This commit looks good
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
jenkins-ci/cloud-client-test Success
Details
jenkins-ci/unittests Success
Details
travis-ci/astyle Passed, 656 files (+0 files)
Details
travis-ci/docs Local docs testing has passed
Details
travis-ci/events Passed, runtime is 10213 cycles (+253 cycles)
Details
travis-ci/gitattributestest Local gitattributestest testing has passed
Details
travis-ci/licence_check Local licence_check testing has passed
Details
travis-ci/littlefs Passed, code size is 8372B (+0.00%)
Details
travis-ci/tools-py2.7 Local tools-py2.7 testing has passed
Details
@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

This comment has been minimized.

@kjbracey-arm

kjbracey-arm Oct 15, 2018

Contributor

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.

This comment has been minimized.

@cmonr

This comment has been minimized.

@aashishc1988

aashishc1988 Oct 17, 2018

Contributor

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment