sched_protect(2)

[Christos Zoulas]

Hi again,

On a different subject, I noticed that we don't have a man page for
sched_protect(2), can you please take a stab at writing one?

Best,

christos

[Rocky Hotas]

Hi Christos,

Sent: Sunday, July 31, 2016 at 3:05 PM
Subject: sched_protect(2)

[...]

On a different subject, I noticed that we don't have a man page for
sched_protect(2), can you please take a stab at writing one?

I am just an enthusiast and not a developer; I used pthreads some months ago and noticed that sched_protect is already mentioned in sched(3). Is there something that I can do to help you writing or reviewing the man page, or is this kind of work better fitted for the developers' team?
Bye :),

Rocky

[Christos Zoulas]

On Aug 1, 4:28pm, ***@post.com ("Rocky Hotas") wrote:
-- Subject: Re: sched_protect(2)

| I am just an enthusiast and not a developer; I used pthreads some
| months ago and noticed that sched_protect is already mentioned in
| sched(3). Is there something that I can do to help you writing or
| reviewing the man page, or is this kind of work better fitted for
| the developers' team?

Hi, Rocky,

Anyone can help. As you correctly pointed out, there is a summary
in sched.3, but we need to mention that -1 restores the original
priority (popping a level) and make sure that there is also a link
to it, so 'man sched_protect' works. Please coordinate here with Charles
on who is doing what, so that we don't do things twice.

| Bye :),

Best,

christos

[Charles Cui]

Hi Rocky,

As Christos mentioned, you can help to improve the man pages here.
If you want to take it, please add the information that Christos wants in
the
current page and also makes man sched_protect works.
After you complete it, you can either send the pull request on our github,
https://github.com/ycui1984/posixtestsuite in patches/prioprotect folder,
or post the patch in the mail list, so that we can send you feedbacks.
Let me know if you want to do it, and I will focus on problems in real time
signals.


Thanks Charles.

Post by Christos Zoulas
-- Subject: Re: sched_protect(2)
| I am just an enthusiast and not a developer; I used pthreads some
| months ago and noticed that sched_protect is already mentioned in
| sched(3). Is there something that I can do to help you writing or
| reviewing the man page, or is this kind of work better fitted for
| the developers' team?
Hi, Rocky,
Anyone can help. As you correctly pointed out, there is a summary
in sched.3, but we need to mention that -1 restores the original
priority (popping a level) and make sure that there is also a link
to it, so 'man sched_protect' works. Please coordinate here with Charles
on who is doing what, so that we don't do things twice.
| Bye :),
Best,
christos

[Charles Cui]

Sure, I can do that.

Post by Christos Zoulas
Hi again,
On a different subject, I noticed that we don't have a man page for
sched_protect(2), can you please take a stab at writing one?
Best,
christos

[Rocky Hotas]

Hello Charles, Christos and all!
I've spent all the time I could, in order to get documented about what you need. Anyway, I am completely new about groff formatting directives for manpages, GitHub (never used it) and patches. Maybe I would flood you with questions, before doing anything.
So, I prefer this time to follow your work (https://github.com/ycui1984/posixtestsuite) and trying to learn from it, now that I know what you are going to do. Then, when I feel able to help, I will write you again for another task.
This is the drawback of being an enthusiast, but also a newbie.
Thanks anyway!!!

Rocky
 
 

Sent: Monday, August 01, 2016 at 7:38 PM
From: "Charles Cui" <***@gmail.com>
To: "Christos Zoulas" <***@zoulas.com>
Cc: "Rocky Hotas" <***@post.com>, "tech-userlevelnetbsd.org" <tech-***@netbsd.org>
Subject: Re: sched_protect(2)

Hi Rocky,
 
  As Christos mentioned, you can help to improve the man pages here. 
If you want to take it, please add the information that Christos wants in the 
current page and also makes man sched_protect works. 
After you complete it, you can either send the pull request on our github, 
https://github.com/ycui1984/posixtestsuite    in patches/prioprotect folder,
or post the patch in the mail list, so that we can send you feedbacks. 
Let me know if you want to do it, and I will focus on problems in real time signals. 
 
 
Thanks Charles.
 
2016-08-01 9:55 GMT-07:00 Christos Zoulas <***@zoulas.com[***@zoulas.com]>:On Aug 1,  4:28pm, ***@post.com[***@post.com] ("Rocky Hotas") wrote:
-- Subject: Re: sched_protect(2)

| I am just an enthusiast and not a developer; I used pthreads some
| months ago and noticed that sched_protect is already mentioned in
| sched(3). Is there something that I can do to help you writing or
| reviewing the man page, or is this kind of work better fitted for
| the developers' team?

Hi, Rocky,

Anyone can help. As you correctly pointed out, there is a summary
in sched.3, but we need to mention that -1 restores the original
priority (popping a level) and make sure that there is also a link
to it, so 'man sched_protect' works. Please coordinate here with Charles
on who is doing what, so that we don't do things twice.

| Bye :),

Best,

christos

[Christos Zoulas]

On Aug 3, 11:53am, ***@post.com ("Rocky Hotas") wrote:
-- Subject: Re: sched_protect(2)

| Hello Charles, Christos and all!
| I've spent all the time I could, in order to get documented about what you =
| need. Anyway, I am completely new about groff formatting directives for man=
| pages, GitHub (never used it) and patches. Maybe I would flood you with que=
| stions, before doing anything.
| So, I prefer this time to follow your work (https://github.com/ycui1984/pos=
| ixtestsuite) and trying to learn from it, now that I know what you are goin=
| g to do. Then, when I feel able to help, I will write you again for another=
| task.
| This is the drawback of being an enthusiast, but also a newbie.
| Thanks anyway!!!

Sounds good... But nevertheless try pattern-matching... I.e. see what other
man pages do, or man 7 mdoc But nevertheless try pattern-matching... I.e. see what other
man pages do, or man 7 mdoc.

christos

[Rocky Hotas]

Hi Christos, hi Charles,
maybe I have some little good updates. Feel free to use them only if they can be useful.

Sent: Wednesday, August 03, 2016 at 5:47 PM
Subject: Re: sched_protect(2)
Sounds good... But nevertheless try pattern-matching... I.e. see what other
man pages do, or man 7 mdoc

Yes, sure, I've already done it with the pages in /usr/share/man and I tried to write a test manpage.
Maybe my main trouble was with the GitHub system; it was also not immediate to find the files :), anyway now I succeded in making an attempt to modify the sched.3 manpage.
You can find attached my new version, where I simply added in the sched_protect section (line 158 of the source file):

Note: if
.Fa priority
is set to \-1, the original priority of the caller thread is restored.

I intentionally wrote nothing in the section DESCRIPTION (where the integer value sched_priority is described). Do you prefer to insert something even there, instead?

I can't understand what do you mean about "popping a level" (do you mean maybe that the previously set priority integer is "taken away" from memory?). Moreover: when the functions are listed in the various sections of the man page, they are not in an alphabetical order. Is this desirable, or do you usually prefer to reorder them?

Christos said to create links such that "man sched_protect" will work. But here

https://github.com/ycui1984/posixtestsuite/blob/master/patches/PRIOPROTECT/0008-man-pages-for-sched_protect.patch

both distrib/sets/lists/comp/mi and lib/librt/Makefile already have a reference to sched_protect. Is there any other link to be specified? (I never compiled a package with manpages).
Forgive my inexperience and feel free to trash the attached file if you think it is not appropriate.
Anyway, for any modifications of that man page (adding words, comments) I am now able to edit the file, if I can use this mailing list instead of GitHub.
Bye :)!

Rocky

[Charles Cui]

Never mind Rocky!
I can take this over.


Thanks Charles

Post by Christos Zoulas
-- Subject: Re: sched_protect(2)
| Hello Charles, Christos and all!
| I've spent all the time I could, in order to get documented about what
you =
| need. Anyway, I am completely new about groff formatting directives for
man=
| pages, GitHub (never used it) and patches. Maybe I would flood you with
que=
| stions, before doing anything.
| So, I prefer this time to follow your work (
https://github.com/ycui1984/pos=
| ixtestsuite) and trying to learn from it, now that I know what you are
goin=
| g to do. Then, when I feel able to help, I will write you again for
another=
| task.
| This is the drawback of being an enthusiast, but also a newbie.
| Thanks anyway!!!
Sounds good... But nevertheless try pattern-matching... I.e. see what other
man pages do, or man 7 mdoc But nevertheless try pattern-matching... I.e.
see what other
man pages do, or man 7 mdoc.
christos

[Christos Zoulas]

On Aug 3, 11:40pm, ***@post.com ("Rocky Hotas") wrote:
-- Subject: Re: sched_protect(2)

| Hi Christos, hi Charles,
| maybe I have some little good updates. Feel free to use them only if they can be useful.
|
| > Sent: Wednesday, August 03, 2016 at 5:47 PM
| > From: "Christos Zoulas" <***@zoulas.com>
| > To: "Rocky Hotas" <***@post.com>, "Charles Cui" <***@gmail.com>
| > Cc: "tech-userlevelnetbsd.org" <tech-***@netbsd.org>
| > Subject: Re: sched_protect(2)
| >
| >
| > Sounds good... But nevertheless try pattern-matching... I.e. see what other
| > man pages do, or man 7 mdoc
|
| Yes, sure, I've already done it with the pages in /usr/share/man and I tried to write a test manpage.
| Maybe my main trouble was with the GitHub system; it was also not immediate to find the files :), anyway now I succeded in making an attempt to modify the sched.3 manpage.
| You can find attached my new version, where I simply added in the sched_protect section (line 158 of the source file):
|
| Note: if
| .Fa priority
| is set to \-1, the original priority of the caller thread is restored.
|
| I intentionally wrote nothing in the section DESCRIPTION (where the integer value sched_priority is described). Do you prefer to insert something even there, instead?

I don't know, I did not either.

| I can't understand what do you mean about "popping a level" (do you mean maybe that the previously set priority integer is "taken away" from memory?). Moreover: when the functions are listed in the various sections of the man page, they are not in an alphabetical order. Is this desirable, or do you usually prefer to reorder them?

Yes, it is preferable to have them sorted but I did not do that yet. I tried
to explain what popping a level means though...

| Christos said to create links such that "man sched_protect" will work. But here
|
| https://github.com/ycui1984/posixtestsuite/blob/master/patches/PRIOPROTECT/0008-man-pages-for-sched_protect.patch
|
| both distrib/sets/lists/comp/mi and lib/librt/Makefile already have a reference to sched_protect. Is there any other link to be specified? (I never compiled a package with manpages).
| Forgive my inexperience and feel free to trash the attached file if you think it is not appropriate.
| Anyway, for any modifications of that man page (adding words, comments) I am now able to edit the file, if I can use this mailing list instead of GitHub.
| Bye :)!

Yes, this has been already done. I've ameneded the page, thanks!

christos

[Rocky Hotas]

Hi Christos, hi Charles and all,

Sent: Thursday, August 04, 2016 at 9:12 AM
Subject: Re: sched_protect(2)

[...]

| I intentionally wrote nothing in the section DESCRIPTION (where the integer value sched_priority is described). Do you prefer to insert something even there, instead?
I don't know, I did not either.

In the attached file I wrote a couple of lines there, because I think it is useful for the reader:

Note that this number has also an allowed negative value (see
description of
.Fn sched_protect
below)."

Yes, it is preferable to have them sorted but I did not do that yet. I tried
to explain what popping a level means though...

I had tried yesterday to sort them. But (after reflecting a little bit) I think in the original order they are more "readable". For example, functions like sched_setparam and sched_setparam are one before the other and it is very useful. In an alphabetical order, sched_getparam would be 1st and sched_setparam would be 7th!

Yes, this has been already done. I've ameneded the page, thanks!

Ok for the links!
I would like to make a couple of observations if they could be useful:

- The man page contains description of two functions (sched_setaffinity_np and sched_getaffinity_np) that are not mentioned in the NAME section. If it is not intentional, they should be added even there.
- Christos, you made a great description about "popping" a level. Anyway, from the manual it is not clear if sched_protect with a positive argument increases by one the protected priority of the thread (regardless of the actual value of the argument), or if it increase that priority by the argument instead. In other words, if I call sched_protect(5) and then sched_protect(4), I don't know from the manual if I then should call sched_priority(-1) 9 times in order to restore the original thread priority, or just 2 times, because I called sched_protect two times, regardless of the positive argument. (This is just a consideration; if it is trivial for a programmer to determine the answer, discard this point :)!)

Thanks to you; my work was not so big.
Bye :)

Rocky