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.

460

Might be more clear as:

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

465

a simple lock

597

missed this one

650

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

597

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

597

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

811

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)

818

indicated by the URWLOCK_WRITE_OWNER bit being set,

820

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

821

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

846

The unlock type (read or write)

850

about the identity of the thread

859

How is the one chosen?

865

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

871

the process-private

875

the process-pirvate

892

Maybe:
indicate that there is a waiter

917

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

951–953

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.

977

is more than one

1005

only one l, successful

1009

A request ... not restartable.

An unblocked

1029

sleeping

1040

specifies the sub-request

1050

creating a new object

1051

object's size

1066–1067

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

1069

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.

1076

when only the liveness ... since the file descriptor

1100

return a POSIX

1102

the errno variable

(or just "and errno is set")

1110

points to invalid memory

1115

in the c_clockid

1130

has changed the lock owner thread identifier during unlock.

1136

member of

1140

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)

1158

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

1159

the m_ceilings

1160

is greater than

1163

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

1166

no , after address

1181

The maximum number of

1183

granted ownership of (no the)

1189

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

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

1195

for a non-restartable

1199

for a restartable

1200

without a timeout

[kib]

lib/libc/sys/_umtx_op.2

859

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.

1163

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

1189

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

859

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