ClockPeriod(), ClockPeriod_r()

Get or set a clock period

Synopsis:

#include <sys/neutrino.h>

int ClockPeriod( clockid_t id,
                 const struct _clockperiod * new,
                 struct _clockperiod * old,
                 int reserved );

int ClockPeriod_r( clockid_t id,
                   const struct _clockperiod * new,
                   struct _clockperiod * old,
                   int reserved );

Since:

BlackBerry 10.0.0

Arguments:

id
The clock ID of the clock; one of the following:
  • CLOCK_REALTIME — the clock that maintains the system time.
  • CLOCK_HARMONIC — the clock that maintains the harmonic timer boundary. Timers whose remaining time before expiry is greater than this boundary are considered for timer harmonization; for more information, see " Clocks, timers, and power management " in the Tick, Tock: Understanding the Microkernel's Concept of Time chapter of the BlackBerry 10 OS Programmer's Guide.
new
NULL, or a pointer to a _clockperiod structure that contains the period to set the clock to. This structure contains at least the following members:
  • unsigned long nsec—the period of the clock, in nanoseconds.

    For CLOCK_HARMONIC, this period is in seconds, not nanoseconds.

  • long fract—reserved for future fractional nanoseconds. Set this member to zero.
old
NULL, or a pointer to a _clockperiod structure where the function can store the current period (before being changed by a non-NULL new).
reserved
Set this argument to 0.

Library:

libc

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

Description:

You can use the ClockPeriod() and ClockPeriod_r() kernel calls to get or set the clock period of the clock. These functions are identical except in the way they indicate errors. See the Returns section for details.

  • If you want to get the clock period, consider calling clock_getres() instead of using these kernel calls directly.
  • In order to set the clock period, your process must have the PROCMGR_AID_CLOCKPERIOD ability enabled. For more information, see procmgr_ability().

All the timer_*() calls operate with an accuracy no better than the clock period. Every moment within the QNX Neutrino microkernel is referred to as a tick. A tick's initial length is determined by the clock rate of your processor:

CPU clock speed: Default value:
≥ 40MHz 1 millisecond
< 40MHz 10 milliseconds

Since a very small tick size imposes an interrupt load on the system, and can consume all available processor cycles, the kernel call limits how small a period can be specified. The lowest clock period that can currently be set on any machine is 10 microseconds.

If an attempt is made to set a value that the kernel believes to be unsafe, the call fails with an EINVAL. The timeslice rate (for "round-robin" and "other" scheduling policies) is always four times the clock period (this isn't changeable).

Blocking states

These calls don't block.

Returns:

The only difference between these functions is the way they indicate errors:

ClockPeriod()
If an error occurs, this function returns -1 is and sets errno . Any other value returned indicates success.
ClockPeriod_r()
EOK is returned on success. This function does NOT set errno. If an error occurs, the function can return any value in the Errors section.

Errors:

EFAULT
A fault occurred when the kernel tried to access the buffers provided.
EINVAL
Invalid clock ID. A period was set which wasn't in a range considered safe.
EPERM
The process tried to change the period of the clock without having the required permission; see procmgr_ability().

Classification:

QNX Neutrino

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

Last modified: 2014-06-24



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus