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.
Tags
None
Referenced Files
Unknown Object (File)
Feb 17 2024, 8:57 PM
Unknown Object (File)
Feb 17 2024, 8:57 PM
Unknown Object (File)
Jan 22 2024, 2:20 AM
Unknown Object (File)
Jan 11 2024, 1:58 PM
Unknown Object (File)
Jan 8 2024, 4:58 AM
Unknown Object (File)
Jan 2 2024, 7:45 PM
Unknown Object (File)
Dec 22 2023, 11:18 PM
Unknown Object (File)
Nov 30 2023, 4:31 PM
Subscribers

Diff Detail

Repository
rG FreeBSD src repository
Lint
Lint Not Applicable
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
107
108
124
129

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

134

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.

141

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

142

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

155

or "unrecoverable"

163
164

"The type" or ".Va type"

170

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

171
174
176

Same comment about commas.

181

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
129

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.

142

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.

155

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
155

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
304 ↗(On Diff #96078)

typo

297 ↗(On Diff #96036)

Reads better like

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.