Clocks and timers

Cobalt/POSIX clock and timer services. More...

Collaboration diagram for Clocks and timers:

Functions
int	clock_getres (clockid_t clock_id, struct timespec *tp)
	Get the resolution of the specified clock. More...
int	clock_gettime (clockid_t clock_id, struct timespec *tp)
	Read the specified clock. More...
int	clock_settime (clockid_t clock_id, const struct timespec *tp)
	Set the specified clock. More...
int	clock_nanosleep (clockid_t clock_id, int flags, const struct timespec *rqtp, struct timespec *rmtp)
	Sleep some amount of time. More...
int	nanosleep (const struct timespec *rqtp, struct timespec *rmtp)
	Sleep some amount of time. More...
int	timer_create (clockid_t clockid, const struct sigevent *__restrict__ evp, timer_t *__restrict__ timerid)
	Create a timer. More...
int	timer_delete (timer_t timerid)
	Delete a timer object. More...
int	timer_settime (timer_t timerid, int flags, const struct itimerspec *__restrict__ value, struct itimerspec *__restrict__ ovalue)
	Start or stop a timer. More...
int	timer_gettime (timer_t timerid, struct itimerspec *value)
	Get timer next expiration date and reload value. More...
int	timer_getoverrun (timer_t timerid)
	Get expiration overruns count since the most recent timer expiration signal delivery. More...

Detailed Description

Cobalt/POSIX clock and timer services.

Cobalt supports three built-in clocks:

CLOCK_REALTIME maps to the nucleus system clock, keeping time as the amount of time since the Epoch, with a resolution of one nanosecond.

CLOCK_MONOTONIC maps to an architecture-dependent high resolution counter, so is suitable for measuring short time intervals. However, when used for sleeping (with clock_nanosleep()), the CLOCK_MONOTONIC clock has a resolution of one nanosecond, like the CLOCK_REALTIME clock.

CLOCK_MONOTONIC_RAW is Linux-specific, and provides monotonic time values from a hardware timer which is not adjusted by NTP. This is strictly equivalent to CLOCK_MONOTONIC with Cobalt, which is not NTP adjusted either.

In addition, external clocks can be dynamically registered using the cobalt_clock_register() service. These clocks are fully managed by Cobalt extension code, which should advertise each incoming tick by calling xnclock_tick() for the relevant clock, from an interrupt context.

Timer objects may be created with the timer_create() service using any of the built-in or external clocks. The resolution of these timers is clock-specific. However, built-in clocks all have nanosecond resolution, as specified for clock_nanosleep().

See also

Specification.

Function Documentation

clock_getres()

int clock_getres	(	clockid_t	clock_id,
		struct timespec *	tp
	)

Get the resolution of the specified clock.

This service returns, at the address res, if it is not NULL, the resolution of the clock clock_id.

For both CLOCK_REALTIME and CLOCK_MONOTONIC, this resolution is the duration of one system clock tick. No other clock is supported.

Parameters

clock_id	clock identifier, either CLOCK_REALTIME or CLOCK_MONOTONIC;
tp	the address where the resolution of the specified clock will be stored on success.

Return values

0	on success;
-1	with errno set if: EINVAL, clock_id is invalid;

See also

Specification.

Tags

unrestricted

clock_gettime()

int clock_gettime	(	clockid_t	clock_id,
		struct timespec *	tp
	)

Read the specified clock.

This service returns, at the address tp the current value of the clock clock_id. If clock_id is:

• CLOCK_REALTIME, the clock value represents the amount of time since the Epoch, with a precision of one system clock tick;
• CLOCK_MONOTONIC or CLOCK_MONOTONIC_RAW, the clock value is given by an architecture-dependent high resolution counter, with a precision independent from the system clock tick duration.
• CLOCK_HOST_REALTIME, the clock value as seen by the host, typically Linux. Resolution and precision depend on the host, but it is guaranteed that both, host and Cobalt, see the same information.

Parameters

clock_id	clock identifier, either CLOCK_REALTIME, CLOCK_MONOTONIC, or CLOCK_HOST_REALTIME;
tp	the address where the value of the specified clock will be stored.

Return values

0	on success;
-1	with errno set if: EINVAL, clock_id is invalid.

See also

Specification.

Tags

unrestricted

clock_nanosleep()

int clock_nanosleep	(	clockid_t	clock_id,
		int	flags,
		const struct timespec *	rqtp,
		struct timespec *	rmtp
	)

Sleep some amount of time.

This service suspends the calling thread until the wakeup time specified by rqtp, or a signal is delivered to the caller. If the flag TIMER_ABSTIME is set in the flags argument, the wakeup time is specified as an absolute value of the clock clock_id. If the flag TIMER_ABSTIME is not set, the wakeup time is specified as a time interval.

If this service is interrupted by a signal, the flag TIMER_ABSTIME is not set, and rmtp is not NULL, the time remaining until the specified wakeup time is returned at the address rmtp.

The resolution of this service is one system clock tick.

Parameters

clock_id	clock identifier, either CLOCK_REALTIME or CLOCK_MONOTONIC.
flags	one of: 0 meaning that the wakeup time rqtp is a time interval; TIMER_ABSTIME, meaning that the wakeup time is an absolute value of the clock clock_id.
rqtp	address of the wakeup time.
rmtp	address where the remaining time before wakeup will be stored if the service is interrupted by a signal.

Returns

0 on success;

an error number if:

• EPERM, the caller context is invalid;
• ENOTSUP, the specified clock is unsupported;
• EINVAL, the specified wakeup time is invalid;
• EINTR, this service was interrupted by a signal.

See also

Specification.

Tags

xthread-only, switch-primary

Referenced by clock_settime(), and nanosleep().

clock_settime()

int clock_settime	(	clockid_t	clock_id,
		const struct timespec *	tp
	)

Set the specified clock.

This allow setting the CLOCK_REALTIME clock.

Parameters

clock_id	the id of the clock to be set, only CLOCK_REALTIME is supported.
tp	the address of a struct timespec specifying the new date.

Return values

0	on success;
-1	with errno set if: EINVAL, clock_id is not CLOCK_REALTIME; EINVAL, the date specified by tp is invalid.

See also

Specification.

Tags

unrestricted

References clock_nanosleep().

nanosleep()

int nanosleep	(	const struct timespec *	rqtp,
		struct timespec *	rmtp
	)

Sleep some amount of time.

This service suspends the calling thread until the wakeup time specified by rqtp, or a signal is delivered. The wakeup time is specified as a time interval.

If this service is interrupted by a signal and rmtp is not NULL, the time remaining until the specified wakeup time is returned at the address rmtp.

The resolution of this service is one system clock tick.

Parameters

rqtp	address of the wakeup time.
rmtp	address where the remaining time before wakeup will be stored if the service is interrupted by a signal.

Return values

0	on success;
-1	with errno set if: EPERM, the caller context is invalid; EINVAL, the specified wakeup time is invalid; EINTR, this service was interrupted by a signal.

See also

Specification.

Tags

xthread-only, switch-primary

References clock_nanosleep().

timer_create()

int timer_create	(	clockid_t	clockid,
		const struct sigevent *__restrict__	evp,
		timer_t *__restrict__	timerid
	)

Create a timer.

This service creates a timer based on the clock clockid.

If evp is not NULL, it describes the notification mechanism used on timer expiration. Only thread-directed notification is supported (evp->sigev_notify set to SIGEV_THREAD_ID).

If evp is NULL, the current Cobalt thread will receive the notifications with signal SIGALRM.

The recipient thread is delivered notifications when it calls any of the sigwait(), sigtimedwait() or sigwaitinfo() services.

If this service succeeds, an identifier for the created timer is returned at the address timerid. The timer is unarmed until started with the timer_settime() service.

Parameters

clockid	clock used as a timing base;
evp	description of the asynchronous notification to occur when the timer expires;
timerid	address where the identifier of the created timer will be stored on success.

Return values

0	on success;
-1	with errno set if: EINVAL, the clock clockid is invalid; EINVAL, the member sigev_notify of the sigevent structure at the address evp is not SIGEV_THREAD_ID; EINVAL, the member sigev_signo of the sigevent structure is an invalid signal number; EAGAIN, the maximum number of timers was exceeded, recompile with a larger value.

See also

Specification.

Tags

thread-unrestricted

Referenced by pthread_make_periodic_np().

timer_delete()

int timer_delete

(

timer_t

timerid

)

Delete a timer object.

This service deletes the timer timerid.

Parameters

timerid

identifier of the timer to be removed;

Return values

0	on success;
-1	with errno set if: EINVAL, timerid is invalid; EPERM, the timer timerid does not belong to the current process.

See also

Specification.

Tags

thread-unrestricted

References timer_settime().

timer_getoverrun()

int timer_getoverrun

(

timer_t

timerid

)

Get expiration overruns count since the most recent timer expiration signal delivery.

This service returns timerid expiration overruns count since the most recent timer expiration signal delivery. If this count is more than DELAYTIMER_MAX expirations, DELAYTIMER_MAX is returned.

Parameters

timerid

Timer identifier.

Returns

the overruns count on success;

-1 with errno set if:

• EINVAL, timerid is invalid;
• EPERM, the timer timerid does not belong to the current process.

See also

Specification.

Tags

unrestricted

timer_gettime()

int timer_gettime	(	timer_t	timerid,
		struct itimerspec *	value
	)

Get timer next expiration date and reload value.

This service stores, at the address value, the expiration date (member it_value) and reload value (member it_interval) of the timer timerid. The values are returned as time intervals, and as multiples of the system clock tick duration (see note in section Clocks and timers services for details on the duration of the system clock tick). If the timer was not started, the returned members it_value and it_interval of value are zero.

Parameters

timerid	timer identifier;
value	address where the timer expiration date and reload value are stored on success.

Return values

0	on success;
-1	with errno set if: EINVAL, timerid is invalid. For timerid to be valid, it must belong to the current process.

See also

Specification.

Tags

unrestricted

timer_settime()

timer_settime	(	timer_t	timerid,
		int	flags,
		const struct itimerspec *__restrict__	value,
		struct itimerspec *__restrict__	ovalue
	)

Start or stop a timer.

This service sets a timer expiration date and reload value of the timer timerid. If ovalue is not NULL, the current expiration date and reload value are stored at the address ovalue as with timer_gettime().

If the member it_value of the itimerspec structure at value is zero, the timer is stopped, otherwise the timer is started. If the member it_interval is not zero, the timer is periodic. The current thread must be a Cobalt thread (created with pthread_create()) and will be notified via signal of timer expirations.

When starting the timer, if flags is TIMER_ABSTIME, the expiration value is interpreted as an absolute date of the clock passed to the timer_create() service. Otherwise, the expiration value is interpreted as a time interval.

Expiration date and reload value are rounded to an integer count of nanoseconds.

Parameters

timerid	identifier of the timer to be started or stopped;
flags	one of 0 or TIMER_ABSTIME;
value	address where the specified timer expiration date and reload value are read;
ovalue	address where the specified timer previous expiration date and reload value are stored if not NULL.

Return values

0	on success;
-1	with errno set if: EINVAL, the specified timer identifier, expiration date or reload value is invalid. For timerid to be valid, it must belong to the current process.

See also

Specification.

Tags

xcontext, switch-primary

Referenced by pthread_make_periodic_np(), and timer_delete().