Re: [RFC PATCH v0.1 0/9] UMCG early preview/RFC patchset

Peter Oskolkov [off-list ref] writes:

I've pasted below the content of umcg.rst file that I'll add as a doc
patch to the next version of the patchset. I've also attached a PDF
version of the file rendered, in case it is useful. I also think that
it is a bit early for manpages - I expect the API and/or behavior to
change quite a bit before this is all merged. I'm also not completely
sure whether the manpages should describe the "porcelain API" or the
"plumbing API" (see the .rst below).

Please let me know if you have any questions, comments, or suggestions.

So this is very helpful, thanks.  I've been through it once, and have
some overall comments.

 - Parts of it read more like a requirements document.  A document going
   into the kernel should describe what the code actually does, not what
   we think it should be.

 - I would make a serious effort to get a handle on the terminology.
   The term "kernel thread" has a meaning other than the one you give
   it; saying "kernel thread" here will lead to a lot of confusion.  I
   hesitate to suggest terms because I'm terrible at naming (just ask my
   kids), but I would pick clear and concise names for your "server
   threads" and "worker threads", then stick to them.

 - The library documentation is good to have, but it will really be
   necessary to document the system calls as well.  *That* is the part
   that the kernel community will have to support forever if this is
   merged.

Thanks,

jon