Page MenuHomeFreeBSD

Improve documentation for pthread mutex attributes; describe internals and quirks of the private and process-shared locks
ClosedPublic

Authored by kib on Oct 1 2021, 1:57 AM.

Diff Detail

Repository
R10 FreeBSD src repository
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

kib requested review of this revision.Oct 1 2021, 1:57 AM
kib created this revision.
lib/libthr/libthr.3
266 ↗(On Diff #96036)

Maybe "all synchronization objects (e.g., pthread_mutex_t) ..."

266 ↗(On Diff #96036)
267 ↗(On Diff #96036)
269 ↗(On Diff #96036)
271 ↗(On Diff #96036)
272 ↗(On Diff #96036)
273 ↗(On Diff #96036)
286 ↗(On Diff #96036)
291 ↗(On Diff #96036)
308 ↗(On Diff #96036)

Maybe s/this/the FreeBSD/, assuming I understood correctly.

308 ↗(On Diff #96036)
311 ↗(On Diff #96036)
share/man/man3/pthread_mutexattr.3
106
107
123
128

Is "priority ceiling" explained anywhere? It is mentioned above with pthread_mutexattr_setprioceiling() but not really explained.

133

I think it should be "the robustness attribute" or something like that. Otherwise it seems like "robust" is an adjective for "attribute" and it reads strangely.

140

"owning the mutex" and "while holding the mutex lock" are saying the same thing.

141

In what scenario can another thread unlock a mutex held by a terminated thread?

154

or "unrecoverable"

162
163

"The type" or ".Va type"

169

I'd add commas after "recursive locking" and "current thread". Otherwise it sounds like "recursive" applies to both locking and unlocking.

170
173
175

Same comment about commas.

180

or "causes an error to be returned" as you wrote above.

kib marked 27 inline comments as done.Oct 1 2021, 4:42 PM
kib added inline comments.
share/man/man3/pthread_mutexattr.3
128

Basically the sentence above is the definition of the ceiling. SUSv8 contains much more elaborate description, I am not sure that we want to copy/paste it there.

Might be in the next iteration, some text could be composed.

141

This is mostly literal text from SUSv8. For normal and default non-robust types, they state that unlocking locked but not owned mutex is UB. They also talk about an option of not storing id of the owning thread for such mutexes in rationale. It is as if they want to avoid preventing an implementation from disallowing that.

And for robust mutexes, unlock from other thread is the way in which the abandoned mutex is handled. This is described by the PTHREAD_MUTEX_ROBUST item below.

154

I believe I took the term from SUS.

kib marked 3 inline comments as done.

Handle the batch of Mark' notes.

markj added inline comments.
share/man/man3/pthread_mutexattr.3
154

SUS seems to say "unusable"? In any case, I forgot that "unrepairable" is also an option, there was a typo in the initial version is all. I have no preference, they all seem correct.

This revision is now accepted and ready to land.Oct 1 2021, 8:38 PM
lib/libthr/libthr.3
297 ↗(On Diff #96036)

Reads better like

304 ↗(On Diff #96078)

typo

kib marked 3 inline comments as done.

'unusable'
Fixes from jilles

This revision now requires review to proceed.Oct 1 2021, 10:37 PM
This revision was not accepted when it landed; it landed in state Needs Review.Oct 5 2021, 3:40 AM
This revision was automatically updated to reflect the committed changes.