![]() |
![]() |
![]() |
![]() |
Set a timeout on a blocking state
#include <time.h> int timer_timeout( clockid_t id, int flags, const struct sigevent* notify, const struct timespec* ntime, struct timespec* otime ); int timer_timeout_r( clockid_t id, int flags, const struct sigevent* notify, const struct timespec* ntime, struct timespec* otime );
While the processor isn't in a power-saving mode, CLOCK_SOFTTIME behaves the same as CLOCK_REALTIME.
libc
Use the -l c option to qcc to link against this library. This library is usually included automatically.
The timer_timeout() and timer_timeout_r() functions set a timeout on any kernel blocking state. These functions are identical except in the way they indicate errors. See the Returns section for details.
![]() |
The timer_timeout() function is a cover for TimerTimeout() that uses a timespec structure instead of a uint64_t to specify the timeout. |
The following table shows the blocking states that are entered as a result of certain kernel calls, along with the corresponding timeout state bits that you can use in the flags argument:
Call | Blocking state | Timeout state |
---|---|---|
InterruptWait() | STATE_INTR | _NTO_TIMEOUT_INTR |
MsgReceive(), MsgReceivePulse(), MsgReceivePulsev(), MsgReceivev() | STATE_RECEIVE | _NTO_TIMEOUT_RECEIVE |
MsgSend(), MsgSendnc(), MsgSendsv(), MsgSendsvnc(), MsgSendv(), MsgSendvnc(), MsgSendvs(), MsgSendvsnc() | STATE_SEND or STATE_REPLY | _NTO_TIMEOUT_SEND or _NTO_TIMEOUT_REPLY |
SignalSuspend() | STATE_SIGSUSPEND | _NTO_TIMEOUT_SIGSUSPEND |
SignalWaitinfo() | STATE_SIGWAITINFO | _NTO_TIMEOUT_SIGWAITINFO |
SyncCondvarWait() | STATE_CONDVAR | _NTO_TIMEOUT_CONDVAR |
SyncMutexLock() | STATE_MUTEX | _NTO_TIMEOUT_MUTEX |
SyncSemWait() | STATE_SEM | _NTO_TIMEOUT_SEM |
ThreadJoin() | STATE_JOIN | _NTO_TIMEOUT_JOIN |
For example, to set a timeout on MsgSendv(), specify _NTO_TIMEOUT_SEND | _NTO_TIMEOUT_REPLY for the flags argument.
Here's what happens to the timer:
![]() |
A relative timeout starts when you call timer_timeout(), not when the blocking state is entered. It's possible to get preempted after calling timer_timeout() but before the blocking kernel call. |
The timer_timeout() function always operates on a one-shot basis. When one of the above kernel calls returns (or is interrupted by a signal), the timeout request is removed from the system. Only one timeout per thread may be in effect at a time. A second call to timer_timeout(), without calling one of the above kernel functions, replaces the existing timeout on that thread. A call with flags set to zero ensures that a timeout won't occur on any state. This is the default when a thread is created.
Always call timer_timeout() just before the function that you wish to time out. For example:
... event.sigev_notify = SIGEV_UNBLOCK; timeout.tv_sec = 10; timeout.tv_nsec = 0; timer_timeout( CLOCK_REALTIME, _NTO_TIMEOUT_SEND | _NTO_TIMEOUT_REPLY, &event, &timeout, NULL ); MsgSendv( coid, NULL, 0, NULL, 0 ); ...
If you call timer_timeout() followed by a kernel call that can't cause the thread to block (e.g., ClockId()), the results are undefined.
If a signal handler is called between the calls to timer_timeout() and MsgSendv(), the timer_timeout() values are saved during the signal handler and then are restored when the signal handler exits.
If the timeout expires, the kernel acts upon the event specified by the sigevent structure pointed to by the notify argument. We recommend the following event types in this case:
Only SIGEV_UNBLOCK guarantees that the kernel call unblocks. A signal may be ignored, blocked, or accepted by another thread and a pulse can only unblock a MsgReceivev(). If a NULL is passed for event then SIGEV_UNBLOCK is assumed. In this case, a timed out kernel call will return failure with an error of ETIMEDOUT.
![]() |
MsgSendv() won't unblock on SIGEV_UNBLOCK if the server has already received the message via MsgReceivev() and has specified _NTO_CHF_UNBLOCK in the flags argument to its ChannelCreate() call. In this case, it's up to the server to do a MsgReplyv() or MsgError(). |
The timeout:
( tv_sec × 1000000000 + tv_nsec ) / ( size of timer tick ) nanoseconds
where tv_sec and tv_nsec are fields of the timespec structure (defined in <time.h>).
![]() |
Because of the nature of time measurement, the timer might actually expire later than the specified time. For more information, see the Tick, Tock: Understanding the Neutrino Microkernel's Concept of Time chapter of the QNX Neutrino Programmer's Guide. |
If you don't wish to block for any time, you can pass a NULL for ntime in which case no timer is used, the event is assumed to be SIGEV_UNBLOCK and an attempt to enter a blocking state as set by flags will immediately return with ETIMEDOUT. Although a questionable practice, this can be used to poll potential blocking kernel calls. For example, you can poll for messages using MsgReceivev() with an immediate timeout. A much better approach is to use multiple threads and have one block while waiting for messages.
If you set flags to _NTO_TIMEOUT_NANOSLEEP, then:
timer_timeout( CLOCK_REALTIME, _NTO_TIMEOUT_NANOSLEEP, NULL, &ntime, &otime );
The kernel calls don't block unless _NTO_TIMEOUT_NANOSLEEP is specified in flags. In this case, the calls block as follows:
Safety: | |
---|---|
Cancellation point | No |
Interrupt handler | No |
Signal handler | Yes |
Thread | Yes |
sigevent, TimerCreate(), TimerInfo(), TimerTimeout()
Clocks, Timers, and Getting a Kick Every So Often chapter of Getting Started with QNX Neutrino
Tick, Tock: Understanding the Neutrino Microkernel's Concept of Time chapter of the QNX Neutrino Programmer's Guide
![]() |
![]() |
![]() |
![]() |