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

Update documentation for the ConditionVariable API #8511

Merged
merged 5 commits into from Oct 27, 2018

Conversation

Projects
None yet
6 participants
@scartmell-arm
Contributor

scartmell-arm commented Oct 23, 2018

Description

  • Hide protected member structures from doxygen.
  • Add some more details/comments to the example.
  • Add some defined/undefined behaviours.
  • Add some additional details to function documentation

Pull request type

[ ] Fix
[ ] Refactor
[ ] Target update
[ ] Functionality change
[X] Docs update
[ ] Test update
[ ] Breaking change
docs(api-condvar): Update documentation for the ConditionVariable API
- Hide protected member structures from doxygen.
- Add some more details/comments to the example.
- Add some defined/undefined behaviours.
- Add some additional details to function documentation
Copy edit ConditionVariable.h
Copy edit file, including existing text.

@cmonr cmonr removed the rollup PR label Oct 24, 2018

@0xc0170 0xc0170 requested a review from ARMmbed/mbed-os-maintainers Oct 24, 2018

@cmonr cmonr added needs: work and removed needs: CI labels Oct 25, 2018

melwee01 added some commits Oct 25, 2018

@cmonr cmonr added needs: CI and removed needs: work labels Oct 25, 2018

@cmonr cmonr referenced this pull request Oct 26, 2018

Merged

Rollup PR: UK Docathon pt2 #8552

@cmonr

This comment has been minimized.

Contributor

cmonr commented Oct 26, 2018

Note: This PR is now a part of a rollup PR (#8552).

No further work is needed here, as once that PR is merged, this PR will also be closed and marked as merged.

@@ -90,7 +90,7 @@ struct Waiter;
* Mutex mutex;
* ConditionVariable cv(mutex);
*
* // These variables are protected by locking mutex
* // These variables are protected by locking mutex.

This comment has been minimized.

@kjbracey-arm

kjbracey-arm Oct 26, 2018

Contributor

I guess that should be locking the mutex

Show resolved Hide resolved rtos/ConditionVariable.h
*
* // Wait for a condition to change
* cond.wait();
* while (done == false) {

This comment has been minimized.

@kjbracey-arm

kjbracey-arm Oct 26, 2018

Contributor

Good point on making this a while loop. do is pretty dangerous with a condition variable.

But == false or == true is bad style

Either done isn't a boolean, in which case it's actively dangerous, or it is a boolean, in which case it's just obfuscation.

if (done) or while (!done) on a boolean reads more like natural language.

Show resolved Hide resolved rtos/ConditionVariable.h Outdated
Show resolved Hide resolved rtos/ConditionVariable.h
* - The order which in which waiting threads acquire the condition variable's
* - Calling wait if the mutex is not locked by the current thread is undefined
* behavior.
* - The order in which waiting threads acquire the condition variable's
* mutex after ConditionVariable::notify_all is called is undefined.

This comment has been minimized.

@kjbracey-arm

kjbracey-arm Oct 26, 2018

Contributor

unspecified

* called and there are one or more waiters and one or more threads attempting
* to acquire the condition variable's mutex the order in which the mutex is
* called and there are one or more waiters, and one or more threads
* attempting to acquire the condition variable's mutex the order in which the mutex is
* acquired is undefined.

This comment has been minimized.

@kjbracey-arm

kjbracey-arm Oct 26, 2018

Contributor

unspecified

Also spurious notifications below are unspecified, but don't seem to be able to put a comment there.

@0xc0170

This comment has been minimized.

Member

0xc0170 commented Oct 26, 2018

@melwee01 can you respond to the latest @kjbracey-arm comments in the rollup PR (it failed just now so will need to restart CI, will wait for the update before I restart, investigating why it compiled some code that should not).

@cmonr cmonr merged commit 98e6d53 into ARMmbed:master Oct 27, 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, 677 files (+0 files)
Details
travis-ci/docs Local docs testing has passed
Details
travis-ci/events Passed, runtime is 9946 cycles (-340 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
Details
travis-ci/tools-py2.7 Local tools-py2.7 testing has passed
Details

@scartmell-arm scartmell-arm deleted the scartmell-arm:docs-condition-variable-refactor branch Dec 5, 2018

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