Kernel timeouts

QNX Neutrino lets you have a timeout associated with all kernel blocking states. We talked about the blocking states in the Processes and Threads chapter, in the section “Kernel states.” Most often, you'll want to use this with message passing; a client will send a message to a server, but the client won't want to wait “forever” for the server to respond. In that case, a kernel timeout is suitable. Kernel timeouts are also useful with the pthread_join() function. You might want to wait for a thread to finish, but you might not want to wait too long.

Here's the definition for the TimerTimeout() function call, which is the kernel function responsible for kernel timeouts:

#include <sys/neutrino.h>

int
TimerTimeout (clockid_t id,
              int flags,
              const struct sigevent *notify,
              const uint64_t *ntime,
              uint64_t *otime);

This says that TimerTimeout() returns an integer (a pass/fail indication, with -1 meaning the call failed and set errno, and zero indicating success). The time source (CLOCK_REALTIME, etc.) is passed in id, and the flags parameter gives the relevant kernel state or states. The notify should always be a notification event of type SIGEV_UNBLOCK, and the ntime is the relative time when the kernel call should timeout. The otime parameter indicates the previous value of the timeout—it's not used in the vast majority of cases (you can pass NULL).

Note: It's important to note that the timeout is armed by TimerTimeout(), and activated on entry into one of the kernel states specified by flags. It is cleared upon return from any kernel call. This means that you must re-arm the timeout before each and every kernel call that you want to be timeout-aware. You don't have to clear the timeout after the kernel call; this is done automagically.