Document thr_suspend(2) and thr_wake(2).

[kib]

In case of timeout, ETIMEDOUT is returned, not EWOULDBLOCK.

[wblock]

lib/libc/sys/thr_suspend.2

53

s/in suspended/in a suspended/

57

"elapsion" is not a word, although it seems reasonable enough to make me wonder why.

by elapsing of the timeout specified in the

72

Break the sentence here, also add articles:

call, the thread is not put into a suspended state.
Instead, the call

78

s/with/with an/

83

s/Same as/As/

85

called from another thread, the next

92

Passive -> active:
s/will return/returns/

(Backslash is not needed before dash.)

lib/libc/sys/thr_wake.2

55

s/threads/thread's/

This is another very long and complex sentence which is hard to understand. Maybe:

Passing the thread identifier of the executing thread (see
.Xr thr_self 2 )
to
.Fn thr_wake
sets a thread's flag to cause the next signal-interruptible sleep of that thread in the kernel
to fail immediately with the
.Er EINTR
error.

62

Just "If".

68

s/of/of the/

78

No backslash needed before dash.

84

s/the following/these/

[emaste]

lib/libc/sys/thr_suspend.2

55

I would probably say "terminated by another thread calling", although terminated has the wrong connotation imho.

"The state is exited by another thread calling" maybe

57

"elapsing of the timeout" sounds awkward to me though
@wblock, what about "by the timeout (specified in the timeout argument) elapsing"?
it really is a shame elapsion is not a word

[emaste]

lib/libc/sys/thr_suspend.2

57

cem suggested "by expiration of the timeout"

[kib]

wblock fixes.

[kib]

Clarify ESRCH when tid is not for !curproc.

[jilles]

lib/libc/sys/thr_suspend.2

49

.Xr pthread_cond_timedwait 3 seems a closer match.

107

The specified timeout elapsed. (or: expired)

111

Hmm, isn't this a simple special case of the above [ETIMEDOUT] error?

128

The current libthr does not use this function.

lib/libc/sys/thr_wake.2

48

.Xr pthread_cond_broadcast 3 seems a closer match.

[kib]

lib/libc/sys/thr_suspend.2

49

Well, condition variable is both more cumbersome to use (needs mutex) and requires more mutual involvement of the suspender and victim. Sometimes it is good, when you want a consistent state at the safe suspension point. Sometimes it contradicts the intent of using the suspension, e.g. when you just want to look at a stuff without other threads intervening.

I added references to cond_wait and broadcast, but did not removed suspend_np and resume_np.

111

Yes, but I think that some explicitness there is useful, same as e.g. select(2) man notes that poll is performed with zero timeval.

128

Yes, I know, and thr_wake is used, but not for resume. Intent of the note is to inform that the interface is mostly the internal interface between kernel and some threading library, not inform about exact implementation details.

Do you still request to remove the second half of the sentence ?

[kib]

Some changes due to jilles notes.

[bjk]

lib/libc/sys/thr_suspend.2

58

"This state", probably.

63

It is the act of delivery, not the signal itself, that effects the wakeup, as I understand it. So, "or by the delivery of a signal to the suspended thread"?

69

Maybe "explicit thr_wake"?

73

Maybe "If a wake from thr_wake was delivered before [...]"

79

"If a thread previously called thr_wake with its own thread identifier [...]"

94

This looks like ".Rv -std thr_wait"?

113

"a zero time interval"

125

s/the$//

lib/libc/sys/thr_wake.2

55

(There are separate .Po and .Pc macros, though I don't always recommend their use.)

62

s/the/an/

80

.Rv -std again, I think.

104

s/the//

[jilles]

lib/libc/sys/thr_suspend.2

49

Hmm, I don't think pthread_suspend_np should be recommended like this because the risk of lost wakeups and inconsistent state is high, and it should not be the first option considered. A condition variable (or a semaphore) needs a bit more setup but is easier to get right. pthread_suspend_np does belong in the SEE ALSO section because of the similarity in name.

111

OK.

128

I suppose it can be replaced with something that is not factually incorrect, such as

The
.Fn thr_suspend
system call is non-standard and is only intended for implementing threading.

[kib]

lib/libc/sys/thr_suspend.2

49

IMO the reciprocal requirements of the semaphore or condvar is what makes crucial difference with pthread_suspend_np(3). And I think that there are legitimate cases where preemptive suspension is wanted and is the only robust approach. It is more related to debugging/introspective code, and cannot substitute normal synchonization.

I reworded the sentence to give the advise you want to give, but still mention pthread_suspend_np (which I want).

[kib]

bjk and jilles notes.

[jilles]

lib/libc/sys/thr_suspend.2

49

I like this idea but I don't like the word "voluntaristic". Perhaps s/​for typical safe but voluntaristic suspension/​for typical safe suspension with cooperation of the thread being suspended/.

lib/libc/sys/thr_wake.2

51

Please use similar wording here as in the corresponding part of thr_suspend.2.

[kib]

reworded 'voluntaristic'

[wblock]

lib/libc/sys/thr_suspend.2

57

Maybe

when the time specified by
.Fa timeout
has elapsed,

[kib]

lib/libc/sys/thr_suspend.2

57

Do you mean the following (diff is against the committed version):

diff --git a/lib/libc/sys/thr_suspend.2 b/lib/libc/sys/thr_suspend.2
index 61320ea..b470d18 100644
--- a/lib/libc/sys/thr_suspend.2
+++ b/lib/libc/sys/thr_suspend.2
@@ -61,9 +61,9 @@ system call puts the calling thread in a suspended state, where it is
 not eligible for CPU time.
 This state is exited by another thread calling
 .Xr thr_wake 2 ,
-by expiration of the timeout specified in the
+when the time interval specified by
 .Fa timeout
-argument,
+has elapsed,
 or by the delivery of a signal to the suspended thread.
 .Pp
 If the

[wblock]

lib/libc/sys/thr_suspend.2

57

I think that works, yes. "time interval" can be changed to just "interval", but either way. Thanks!