Page MenuHomeFreeBSD

Document libthr kernel interface.
ClosedPublic

Authored by kib on May 12 2016, 10:48 AM.

Details

Summary

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.

Diff Detail

Repository
rS FreeBSD src repository - subversion
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; 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
or even is an individual one

413 ↗(On Diff #16255)

up a limited number of threads from a given sleep queue

kib marked 44 inline comments as done.May 13 2016, 2:58 PM
kib added inline comments.
lib/libc/sys/_umtx_op.2
399 ↗(On Diff #16255)

I reformulated this by adding 'byte', i.e. ... the address of the start byte ...'.
I can write a perverse example where e.g. the first 4 bytes are shared and the rest is not. In this case the lock is shareable.

kib edited edge metadata.
kib marked an inline comment as done.

Handle the next batch of Ed' corrections.

lib/libc/sys/_umtx_op.2
399 ↗(On Diff #16255)

Oh, I see. OK.

459 ↗(On Diff #16288)

Might be more clear as:

user's duty ...
ensure lock acquire and release memory semantics, if the

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

kib marked 5 inline comments as done.May 13 2016, 3:25 PM

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

kib edited edge metadata.

More refinements after Ed' proof-reading.

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

kib marked an inline comment as done.
kib edited edge metadata.

Article missed.

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
(It's hard for me to explain article choice here, but "a lock" just sounds right to me in this context)

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:
indicate that there is a waiter

916 ↗(On Diff #16288)

Wake up multiple sleeping threads
or
Wake up a batch of 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.
The sleep queue is always one for a normal mutex type.

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.
Perhaps "an alive" is in fact better to match UMTX_SHM_ALIVE though. Keep it if you think it'll be more clear to readers.

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..."
or just "or timeout.tv_nsec is greater" (no need to repeat member again here I'd say)

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
(or "owned by another thread", as you see fit)

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

kib marked 39 inline comments as done.May 13 2016, 7:06 PM
kib added inline comments.
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'.

kib edited edge metadata.
kib marked 2 inline comments as done.

More fixes.

lib/libc/sys/_umtx_op.2
1197 ↗(On Diff #16305)

a timeout in the uaddr1 and uaddr2 arguments, and timed

858 ↗(On Diff #16288)

Yeah, definitely not useful to repeat it again.
Do you think it's valuable to write something like "one writer is woken up, as described in the SLEEP QUEUES subsection"?

kib marked 2 inline comments as done.
kib edited edge metadata.

More corrections.

emaste edited edge metadata.

LGTM

This revision is now accepted and ready to land.May 14 2016, 1:47 AM
This revision was automatically updated to reflect the committed changes.