timer_timeout(), timer_timeout

Set a timeout on a blocking state

Synopsis:

#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 );

Arguments:

id

The clock to use to implement the timeout; one of:

CLOCK_REALTIME — the standard POSIX-defined clock. Timers based on this clock wake up the processor if it's in a power-saving mode.
CLOCK_SOFTTIME — (a QNX Neutrino extension) this clock is active only when the processor isn't in a power-saving mode. For example, an application using a CLOCK_SOFTTIME timer to sleep wouldn't wake up the processor when the application was due to wake up. This will allow the processor to enter a power-saving mode.
While the processor isn't in a power-saving mode, CLOCK_SOFTTIME behaves the same as CLOCK_REALTIME.
CLOCK_MONOTONIC — this clock always increases at a constant rate and can't be adjusted.

For more information about the different clocks, see "Other clock sources" in the Clocks, Timers, and Getting a Kick Every So Often of Getting Started with QNX Neutrino.

flags

Flags that control the function's behavior. The value can be either:

TIMER_TOLERANCE to specify the amount of the tolerance to allow the kernel in low-power situations
or:
a combination of zero or more bits that specify which states the timeout applies to (see below). You can also OR in the following bits:
- TIMER_ABSTIME — set an absolute expiration time. If you don't set this bit, the function sets a relative expiration time.
- TIMER_PRECISE — override any default tolerance that was set for the process (see procmgr_timer_tolerance()).

notify

A pointer to a sigevent structure that defines the event that the kernel acts on if the timeout expires; see below.

If you specify TIMER_TOLERANCE in the flags, this argument must be NULL.

ntime

NULL, or a pointer to a timespec structure that specifies the timeout or timer tolerance, in nanoseconds. If this argument is NULL, the timeout occurs immediately (see below), or the function doesn't change the timer tolerance, depending on the flags.

otime

NULL, or a pointer to a location where the function can store some data, depending on the flags:

TIMER_TOLERANCE — the previous timer tolerance.
_NTO_TIMEOUT_NANOSLEEP — the time remaining in the sleep.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The timer_timeout() and timer_timeout_r() functions set the timeout ntime on any kernel blocking state. These functions are identical except in the way they indicate errors. See the Returns section for details.

Note: The timer_timeout() function is a cover for TimerTimeout() that uses a timespec structure (specifying seconds and nanoseconds) instead of a uint64_t (specifying nanoseconds) for the ntime and otime arguments.

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(), MsgReceivev(), MsgReceivePulse(), MsgReceivePulsev()	STATE_RECEIVE	_NTO_TIMEOUT_RECEIVE
MsgDeliverEvent(), MsgError(), MsgRead(), MsgReadv(), MsgReply(), MsgReplyv(), MsgWrite(), MsgWritev()	STATE_REPLY	_NTO_TIMEOUT_REPLY
MsgSend(), MsgSendnc(), MsgSendsv(), MsgSendsvnc(), MsgSendv(), MsgSendvnc(), MsgSendvs(), MsgSendvsnc()	STATE_SEND or STATE_REPLY	_NTO_TIMEOUT_SEND or _NTO_TIMEOUT_REPLY
MsgSendPulse()	STATE_NET_SEND or STATE_NET_REPLY	Timing out on these states isn't supported
SignalKill()	STATE_NET_SEND or STATE_NET_REPLY	Timing out on these states isn't supported
SignalSuspend()	STATE_SIGSUSPEND	_NTO_TIMEOUT_SIGSUSPEND
SignalWaitinfo()	STATE_SIGWAITINFO	_NTO_TIMEOUT_SIGWAITINFO
SyncCondvarWait()	STATE_CONDVAR or STATE_MUTEX	_NTO_TIMEOUT_CONDVAR or _NTO_TIMEOUT_MUTEX
SyncMutexLock()	STATE_MUTEX	_NTO_TIMEOUT_MUTEX
SyncSemWait()	STATE_SEM	_NTO_TIMEOUT_SEM
ThreadCtl()	STATE_WAITPAGE	Timing out on this state isn't supported
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:

When you call timer_timeout(), the timer is armed; the timer structure is created, and a relative timeout is converted into an absolute one.
When the kernel attempts to enter a blocking state specified in flags, the timer is activated. That is, the timer is placed on the active timer list, and the kernel starts to check the timeout against the current time; if it's already past, the kernel delivers the event right away.
When one of the above kernel calls completes without blocking, or the kernel call blocks but unblocks before the timeout expires, or the timeout expires, the timer is cleared.

Note: 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_MONOTONIC, _NTO_TIMEOUT_SEND | _NTO_TIMEOUT_REPLY, 
               &event, &timeout, NULL );
MsgSendv( coid, NULL, 0, NULL, 0 );
...

There's one exception to this rule: if you want to set the timer tolerance, you need to call timer_timeout() twice, once with flags set to TIMER_TOLERANCE, and once to set the timeout. It doesn't matter which order you do this in.

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:

SIGEV_SIGNAL
SIGEV_SIGNAL_CODE
SIGEV_SIGNAL_THREAD
SIGEV_PULSE
SIGEV_UNBLOCK
SIGEV_INTR

Only SIGEV_UNBLOCK guarantees that the kernel call unblocks. A signal may be ignored, blocked, or accepted by another thread, and a pulse can unblock only a MsgReceivev(). If you specify NULL for notify, then SIGEV_UNBLOCK is assumed. In this case, a timed-out kernel call returns failure with an error of ETIMEDOUT.

Note: MsgSend*() doesn't unblock on SIGEV_UNBLOCK if the server has already received the message via MsgReceive*() 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 MsgReply*() or MsgError().

The timeout:

is specified by the ntime argument
is relative to the current time (when timer_timeout() is called), unless flags includes TIMER_ABSTIME, which makes the timeout occur at the absolute time set in ntime
occurs on a clock tick (see ClockPeriod()) so the actual wakeup time is a minimum of:
```
  ( 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>).

Note: 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 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:

These calls block in the STATE_NANOSLEEP state until the timeout occurs or a signal unblocks the thread. You can use this to implement an efficient kernel sleep as follows:
```
timer_timeout( CLOCK_MONOTONIC, _NTO_TIMEOUT_NANOSLEEP, NULL, &ntime, &otime );
  
```
If otime isn't NULL, the kernel sets *otime to the time remaining in the sleep, in nanoseconds.

Blocking states

The kernel calls don't block unless you specify _NTO_TIMEOUT_NANOSLEEP in flags. In this case, the calls block as follows:

STATE_NANOSLEEP: The calling thread blocks for the requested time period.

Returns:

The previous flags. If an error occurs:

timer_timeout() returns -1 and sets errno.
timer_timeout_r() returns the negative of a value from the Errors section and doesn't set errno.

Errors:

EAGAIN

All kernel timer entries are in use.

EFAULT

A fault occurred when the kernel tried to access ntime, otime, or notify.

EINTR

The call was interrupted by a signal.

EINVAL

Invalid arguments:

The id argument doesn't specify a valid clock ID.
If you specified TIMER_TOLERANCE in the flags, you also set other bits in the flags, or notify isn't NULL.

Classification:

QNX Neutrino

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	Yes
Thread	Yes

timer_timeout(), timer_timeout_r()