Document libthr kernel interface.

[kib]

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.

[emaste]

lib/libc/sys/_umtx_op.2

365

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.

378

A sleep queue

384

can omit the , here

385

enables the construction of process-shared locks.

389

A related

391

creating sleep queues

397

allowing the lock scope to be limited regardless

400

I'm not sure "start of" is necessary, it should be clear from context (and there is an example below).

407

on a little-endian

410

The sleep queue to which a sleeping thread is assigned is individual
or even is an individual one

414

up a limited number of threads from a given sleep queue

[kib]

lib/libc/sys/_umtx_op.2

400

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]

Handle the next batch of Ed' corrections.

[emaste]

lib/libc/sys/_umtx_op.2

400

Oh, I see. OK.

459

Might be more clear as:

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

464

a simple lock

596

missed this one

649

oops correction to my earlier comment. If the timeout expired

[kib]

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

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]

More refinements after Ed' proof-reading.

[emaste]

lib/libc/sys/_umtx_op.2

596

Sorry, not enough context I guess.

After the lock is obtained the new ceiling value

[kib]

Article missed.

[emaste]

Final batch - again only one or two non-trivial comments.

Thanks for writing this up!

lib/libc/sys/_umtx_op.2

810

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

indicated by the URWLOCK_WRITE_OWNER bit being set,

819

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

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

The unlock type (read or write)

849

about the identity of the thread

858

How is the one chosen?

864

or, in the case that the URWLOCK_PREFER_READER flag...

870

the process-private

874

the process-pirvate

891

Maybe:
indicate that there is a waiter

916

Wake up multiple sleeping threads
or
Wake up a batch of sleeping threads

950–952

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

is more than one

1004

only one l, successful

1008

A request ... not restartable.

An unblocked

1028

sleeping

1039

specifies the sub-request

1049

creating a new object

1050

object's size

1065–1066

the last open file descriptor is closed and the last mapping for it is destroyed ?

1068

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

when only the liveness ... since the file descriptor

1099

return a POSIX

1101

the errno variable

(or just "and errno is set")

1109

points to invalid memory

1114

in the c_clockid

1129

has changed the lock owner thread identifier during unlock.

1135

member of

1139

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

maybe "one of the values read from" or "one or more of the values read from"

1158

the m_ceilings

1159

is greater than

1162

Unlock attempted on an object not owned by the current thread
(or "owned by another thread", as you see fit)

1165

no , after address

1180

The maximum number of

1182

granted ownership of (no the)

1188

specified a timeout in the uaddr1 or uaddr2 argument, and timed out...

(assuming "or" instead of "and" is desired)

1194

for a non-restartable

1198

for a restartable

1199

without a timeout

[kib]

lib/libc/sys/_umtx_op.2

858

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

It may be not owned by any thread, for this error, as well.

1188

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]

More fixes.

[emaste]

lib/libc/sys/_umtx_op.2

858

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"?

1198

a timeout in the uaddr1 and uaddr2 arguments, and timed

[kib]

More corrections.

[emaste]

LGTM