Example

For example, say you have a POP3 module and upon successful login you have to scan the contents of the maildrop with a function like this: maildir_get_cur(maildrop);

You might want to do this in your code:

#define POP_WCHAN_CLEANTMP      0
#define POP_WCHAN_GETCUR        1
const char **pop_wchans[] = {"clean_tmp", "get_cur"};

 /* after providing pop_wchans to server_thread_pool_new().. */

server_thread_set_wchan(thread, POP_WCHAN_GETCUR);
maildir_get_cur(maildrop);
server_thread_set_wchan(thread, -1);

Then, lets say your POP3 is being really slow, and you told ServerKit to report statistics on the POP3 personality. You might find that all the threads doing work are showing "get_cur" for the wchan. That immediately shows you that it's not slow because the public network is congested or failing, it is probably a filesystem/storage problem causing maildir_get_cur() to block.

This is similar to the wchan feature of ps, which shows you the wait channel of processes and threads at the system level.

The problem with relying exclusively on the ps wchan is you often have a program that enters the same wait channel at the system level in various contexts, it doesnt have the application-specific contexts. When you set the wchans yourself in the program, you can surround the same system call in all the places it ocurrs in the module with unique ServerKit wchans that include much more context.

Note that this is not exactly free, so you want to make sure you don't call it excessively. If there is a tight loop of calls that block, it's probably better to set and unset the wchan outside the loop in the interest of efficiency. The wchan set function acquires a per-thread-pool mutex every time it is called, so it can become contentious if you overdo it causing unwanted serializing of worker threads.