Document how to handle exiting properly for modules.
Diff Detail
Diff Detail
- Repository
- rS FreeBSD src repository - subversion
- Lint
Lint Passed - Unit
No Test Coverage - Build Status
Buildable 114 Build 114: arc lint + arc unit
Event Timeline
| share/man/man9/kproc.9 | ||
|---|---|---|
| 182 | The section is named EXAMPLES (with an 'S'). | |
| share/man/man9/kthread.9 | ||
| 202 | "used by callers" can lead to confusion about who is doing what. Does it allow other threads to receive a notification when the thread calling kthread_exit() terminates? That might be a more clear thing to say. | |
| 204 | EXAMPLES again. | |
| 207 | Maybe s/The/That/? | |
Comment Actions
Address all but /The/That/ change.. I understand why you suggested it, but it reads not as easily for me... We are only referencing the once example.
| share/man/man9/kproc.9 | ||
|---|---|---|
| 185 | There is a lot of ambiguity here. It reads like the proc pointer is what can be used to tell when a function is no longer running, but probably really means the result of the wakeup. "To know" is also kind of hard to interpret. Should "proc pointer" just be .Fa proc ? A .Fn wakeup is issued on the proc pointer. The (return value? which one?) can be used by callers to determine whether the called function is no longer running. The second sentence could be improved, but it depends on what it is trying to say. ...can be used by callers to determine if the called function is still running or has ended. | |
| 188 | The "this" is nonspecific, we were just talking about ecode and wakeup, so it's not clear whether "this" might be referring to them. The .Sx EXAMPLES section shows how to use .Fn kproc_exit to ensure that a module is unloaded safely. | |
Comment Actions
Technically it is not a hard requirement that you call kthread_exit/kproc_exit(). If you return from your main routine, then fork_exit() calls kproc_exit(0) (should probably be fixed to call kthread_exit() instead).
| share/man/man9/kproc.9 | ||
|---|---|---|
| 359 | The PDROP unlocks the lock. However, a more realistic example is that you re-use an existing lock used in the "do work" section. Often you end up with something like: struct mtx foo_lock;
volatile int foo_quit;
struct proc *foo_kproc;
struct foo_state foo_state;
void
foo_main(void *arg)
{
mtx_lock(&foo_lock);
while (!foo_quit) {
/* do work */
mtx_sleep(&foo_state, &foo_lock, ....);
}
mtx_unlock(&foo_lock);
kproc_exit(0);
}
void
loadmod(void)
{
kproc_create(foo_main, NULL, &foo_proc, 0, 0, "foo proc");
}
void
unloadmod(void)
{
mtx_lock(&foo_lock);
foo_quit = 1;
wakeup(&foo_state);
mtx_sleep(foo_proc, &foo_lock, PDROP, "fooexit", 0);
/* foo_main has called kproc_exit, and module is safe to unload. */
} | |
| share/man/man9/kthread.9 | ||
|---|---|---|
| 204 | "See the EXAMPLES section in .Xr kproc 9 for how to use this to ensure that a module is unloaded safely." - seems a little confusing. "Refer to the EXAMPLES section in .Xr kproc 9 for ways to ensure a module is unloaded safely." - suggested change. | |
| share/man/man9/kproc.9 | ||
|---|---|---|
| 28 | This needs to be bumped again. | |