I wrote man pages for all thr* and _umtx_op syscalls currently used by libthr.
Type-set man pages are available as pdfs at https://kib.kiev.ua/kib/pshared/ , for reading convenience.
Details
Details
- Reviewers
emaste jhb vangyzen - Group Reviewers
manpages - Commits
- rS299735: Document the non-obsoleted kernel interfaces used by libthr.
Diff Detail
Diff Detail
- Repository
- rS FreeBSD src repository - subversion
- Lint
Lint Not Applicable - Unit
Tests Not Applicable
Event Timeline
There are a very large number of changes, so older changes are hidden. Show Older Changes
| lib/libc/sys/_umtx_op.2 | ||
|---|---|---|
| 364 ↗ | (On Diff #16255) | Perhaps just leave the try variant out of the first sentence, and if necessary describe it in a separate sentence? Something like: When a locking request cannot be immediately satisfied the thread is typically put to sleep, which is a non-runnable state terminated by the wake operation. (Most?) Lock operations include a _try variant which returns an error rather than sleeping if the lock cannot be obtained. |
| 377 ↗ | (On Diff #16255) | A sleep queue |
| 383 ↗ | (On Diff #16255) | can omit the , here |
| 384 ↗ | (On Diff #16255) | enables the construction of process-shared locks. |
| 388 ↗ | (On Diff #16255) | A related |
| 390 ↗ | (On Diff #16255) | creating sleep queues |
| 396 ↗ | (On Diff #16255) | allowing the lock scope to be limited regardless |
| 399 ↗ | (On Diff #16255) | I'm not sure "start of" is necessary, it should be clear from context (and there is an example below). |
| 406 ↗ | (On Diff #16255) | on a little-endian |
| 409 ↗ | (On Diff #16255) | The sleep queue to which a sleeping thread is assigned is individual |
| 413 ↗ | (On Diff #16255) | up a limited number of threads from a given sleep queue |
| lib/libc/sys/_umtx_op.2 | ||
|---|---|---|
| 399 ↗ | (On Diff #16255) | I reformulated this by adding 'byte', i.e. ... the address of the start byte ...'. |
| lib/libc/sys/_umtx_op.2 | ||
|---|---|---|
| 459 ↗ | (On Diff #16288) | Might be more clear as: user's duty ... |
| 464 ↗ | (On Diff #16288) | a simple lock |
| 596 ↗ | (On Diff #16288) | missed this one |
| 649 ↗ | (On Diff #16288) | oops correction to my earlier comment. If the timeout expired |
| 399 ↗ | (On Diff #16255) | Oh, I see. OK. |
Comment Actions
Several 'done' button clicks seems to be lost on the previous submit, so I re-clicked them without changing the patch.
| lib/libc/sys/_umtx_op.2 | ||
|---|---|---|
| 596 ↗ | (On Diff #16288) | Does you comment refers to the 'why not adhere' request ? Please see the expanded sentence with a reference to POSIX requirements for pthread_mutex_setprioceiling(3). |
| lib/libc/sys/_umtx_op.2 | ||
|---|---|---|
| 596 ↗ | (On Diff #16288) | Sorry, not enough context I guess. After the lock is obtained the new ceiling value |
Comment Actions
Final batch - again only one or two non-trivial comments.
Thanks for writing this up!
| lib/libc/sys/_umtx_op.2 | ||
|---|---|---|
| 810 ↗ | (On Diff #16288) | request obtains a write lock on the specified |
| 817 ↗ | (On Diff #16288) | indicated by the URWLOCK_WRITE_OWNER bit being set, |
| 819 ↗ | (On Diff #16288) | strip this "already": there are read lock owners already makes sense in the case of a write lock owner, since we're trying to get the write lock ourselves |
| 820 ↗ | (On Diff #16288) | obtain the write-lock. Instead (I'm puzzling over article choice here because I think it should be a at line 810. It makes sense to me because the "struct rwlock" above suggests "a lock".) |
| 845 ↗ | (On Diff #16288) | The unlock type (read or write) |
| 849 ↗ | (On Diff #16288) | about the identity of the thread |
| 858 ↗ | (On Diff #16288) | How is the one chosen? |
| 864 ↗ | (On Diff #16288) | or, in the case that the URWLOCK_PREFER_READER flag... |
| 870 ↗ | (On Diff #16288) | the process-private |
| 874 ↗ | (On Diff #16288) | the process-pirvate |
| 891 ↗ | (On Diff #16288) | Maybe: |
| 916 ↗ | (On Diff #16288) | Wake up multiple sleeping threads |
| 950–952 ↗ | (On Diff #16288) | I think the "where the waiter" is implicit and makes it harder for me to follow. Perhaps: Only normal mutexes are supported by the request. |
| 976 ↗ | (On Diff #16288) | is more than one |
| 1004 ↗ | (On Diff #16288) | only one l, successful |
| 1008 ↗ | (On Diff #16288) | A request ... not restartable. An unblocked |
| 1028 ↗ | (On Diff #16288) | sleeping |
| 1039 ↗ | (On Diff #16288) | specifies the sub-request |
| 1049 ↗ | (On Diff #16288) | creating a new object |
| 1050 ↗ | (On Diff #16288) | object's size |
| 1065–1066 ↗ | (On Diff #16288) | the last open file descriptor is closed and the last mapping for it is destroyed ? |
| 1068 ↗ | (On Diff #16288) | Maybe is a live shared object? I think "an alive shared object" is acceptable but unconventional English. |
| 1075 ↗ | (On Diff #16288) | when only the liveness ... since the file descriptor |
| 1099 ↗ | (On Diff #16288) | return a POSIX |
| 1101 ↗ | (On Diff #16288) | the errno variable (or just "and errno is set") |
| 1109 ↗ | (On Diff #16288) | points to invalid memory |
| 1114 ↗ | (On Diff #16288) | in the c_clockid |
| 1129 ↗ | (On Diff #16288) | has changed the lock owner thread identifier during unlock. |
| 1135 ↗ | (On Diff #16288) | member of |
| 1139 ↗ | (On Diff #16288) | either "or the timeout.tv_nsec member..." |
| 1157 ↗ | (On Diff #16288) | maybe "one of the values read from" or "one or more of the values read from" |
| 1158 ↗ | (On Diff #16288) | the m_ceilings |
| 1159 ↗ | (On Diff #16288) | is greater than |
| 1162 ↗ | (On Diff #16288) | Unlock attempted on an object not owned by the current thread |
| 1165 ↗ | (On Diff #16288) | no , after address |
| 1180 ↗ | (On Diff #16288) | The maximum number of |
| 1182 ↗ | (On Diff #16288) | granted ownership of (no the) |
| 1188 ↗ | (On Diff #16288) | specified a timeout in the uaddr1 or uaddr2 argument, and timed out... (assuming "or" instead of "and" is desired) |
| 1194 ↗ | (On Diff #16288) | for a non-restartable |
| 1198 ↗ | (On Diff #16288) | for a restartable |
| 1199 ↗ | (On Diff #16288) | without a timeout |
| lib/libc/sys/_umtx_op.2 | ||
|---|---|---|
| 858 ↗ | (On Diff #16288) | It is explained in the last paragraph of the SLEEP QUEUES subsection. I do not see it useful to repeat the formulation several times, it was the reason for the subsection writing. |
| 1162 ↗ | (On Diff #16288) | It may be not owned by any thread, for this error, as well. |
| 1188 ↗ | (On Diff #16288) | Both uaddr1 and uaddr2 are needed to specify the timeout, uaddr1 is size, uaddr2 is the pointer to a structure sized by uaddr1. This was explained in 'structures'. |