timer_create()

Arguments:

clock_id

The clock source that you want to use, 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 — in this release, this is equivalent to CLOCK_REALTIME.
• CLOCK_MONOTONIC — this clock always increases at a constant rate and can't be adjusted.
• CLOCK_THREAD_CPUTIME_ID, which refers to the calling thread, or a thread CPU-time clock ID returned by pthread_getcpuclockid() or ClockId(). The timeout that you set for this type of timer represents the thread's execution time.
  Note:

  • The accuracy of this timer depends on the clock period. The thread may exceed the requested execution time, and the actual amount of time it uses is at least the timeout you specified but less than the same amount plus the clock period.
  • At any moment, only one timer in the whole system can be using a specific thread's or process's CPU-time clock ID. If there's already a timer for the given CPU-time clock ID, timer_create() gives an error of EAGAIN.
  • For more information, see Monitoring execution times in the Understanding the Microkernel's Concept of Time chapter of the QNX OS Programmer's Guide.
• CLOCK_PROCESS_CPUTIME_ID, which refers to the calling process, or a process CPU-time clock ID return by clock_getcpuclockid() or ClockId(). The timeout that you set for this type of timer represents the process's execution time. For information about the restrictions on creating these timers, see the CLOCK_THREAD_CPUTIME_ID entry above.

evp

NULL, or a pointer to a sigevent structure containing the event that you want to deliver when the timer fires. The event doesn't need to be registered.

timerid

A pointer to a timer_t object where the function stores the ID of the new timer.

Library:

libc

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

Description:

The timer_create() function creates a per-process timer using the specified clock source, clock_id, as the timing base. The timer is created in the disabled state, and isn't enabled until you call timer_settime().

You can use the timer ID that the function stores in timerid in subsequent calls to timer_gettime(), timer_settime(), and timer_delete().

We recommend the following event types:

• SIGEV_SIGNAL
• SIGEV_SIGNAL_CODE
• SIGEV_SIGNAL_THREAD
• SIGEV_PULSE

If the evp argument is NULL, a SIGALRM signal is sent to your process when the timer expires. To specify a handler for this signal, call sigaction().

Returns:

0

Success. The timerid argument is set to the timer's ID.

-1

An error occurred (errno is set).

Errors:

EAGAIN

One of the following occurred:

• All timers are in use; your process must release one.
• There's already a timer associated with the given CPU-time clock.

EINVAL

One of the following occurred:

• The clock ID is invalid.
• The event type is SIGEV_INTR.

EPERM

The calling process doesn't have the required permission; see procmgr_ability().

Examples:

/*
 * Demonstrate how to set up a timer that, on expiry, sends us a pulse.
 * This example sets the first expiry to 1.5 seconds and the repetition interval
 * to 1.5 seconds.
 */
#include <stdio.h>
#include <stdlib.h>
#include <time.h>
#include <pthread.h>
#include <sys/netmgr.h>
#include <sys/neutrino.h>

#define MY_PULSE_CODE   _PULSE_CODE_MINAVAIL

typedef union {
    struct _pulse   pulse;
    /* your other message structures would go here too */
} my_message_t;

int main()
{
    struct sigevent event;
    struct itimerspec itime;
    timer_t timer_id;
    int chid;
    rcvid_t rcvid;
    my_message_t msg;
    struct sched_param scheduling_params;
    int prio;

    chid = ChannelCreate(0);
 
    /* Get our priority. */
    if (SchedGet( 0, 0, &scheduling_params) != -1)
    {
        prio = scheduling_params.sched_priority;
    }
    else
    {
        prio = 10;
    }
 
    int coid = ConnectAttach(0, 0, chid, _NTO_SIDE_CHANNEL, 0);
    SIGEV_PULSE_INIT(&event, coid, prio, MY_PULSE_CODE, 0);

    timer_create(CLOCK_MONOTONIC, &event, &timer_id);

    itime.it_value.tv_sec = 1;
    /* 500 million nsecs = .5 secs */
    itime.it_value.tv_nsec = 500000000; 
    itime.it_interval.tv_sec = 1;
    /* 500 million nsecs = .5 secs */
    itime.it_interval.tv_nsec = 500000000; 
    timer_settime(timer_id, 0, &itime, NULL);

    /*
     * As of the timer_settime(), we will receive our pulse in 1.5 seconds
     * (the itime.it_value) and every 1.5 seconds thereafter
     * (the itime.it_interval)
     */
    for (;;) {
        rcvid = MsgReceive(chid, &msg, sizeof(msg), NULL);
        if (rcvid == 0) { /* we got a pulse */
            if (msg.pulse.code == MY_PULSE_CODE) {
                printf("we got a pulse from our timer\n");
            } /* else other pulses ... */
        } /* else other messages ... */
    }
    return(EXIT_SUCCESS);
}

Classification:

POSIX 1003.1