Originální popis anglicky:
timer_create - create a per-process timer (
REALTIME)
Návod, kniha: POSIX Programmer's Manual
#include <signal.h>
#include <time.h>
int timer_create(clockid_t
clockid, struct sigevent
*restrict evp,
timer_t *restrict
timerid );
The
timer_create() function shall create a per-process timer using the
specified clock,
clock_id, as the timing base. The
timer_create() function shall return, in the location referenced by
timerid, a timer ID of type
timer_t used to identify the timer
in timer requests. This timer ID shall be unique within the calling process
until the timer is deleted. The particular clock,
clock_id, is defined
in
<time.h>. The timer whose ID is returned shall be in a
disarmed state upon return from
timer_create().
The
evp argument, if non-NULL, points to a
sigevent structure.
This structure, allocated by the application, defines the asynchronous
notification to occur as specified in
Signal Generation and
Delivery when the timer expires. If the
evp argument is NULL,
the effect is as if the
evp argument pointed to a
sigevent
structure with the
sigev_notify member having the value SIGEV_SIGNAL,
the
sigev_signo having a default signal number, and the
sigev_value member having the value of the timer ID.
Each implementation shall define a set of clocks that can be used as timing
bases for per-process timers. All implementations shall support a
clock_id of CLOCK_REALTIME. If the Monotonic Clock option is
supported, implementations shall support a
clock_id of CLOCK_MONOTONIC.
Per-process timers shall not be inherited by a child process across a
fork() and shall be disarmed and deleted by an
exec.
If _POSIX_CPUTIME is defined, implementations shall support
clock_id
values representing the CPU-time clock of the calling process.
If _POSIX_THREAD_CPUTIME is defined, implementations shall support
clock_id values representing the CPU-time clock of the calling thread.
It is implementation-defined whether a
timer_create() function will
succeed if the value defined by
clock_id corresponds to the CPU-time
clock of a process or thread different from the process or thread invoking the
function.
If the call succeeds,
timer_create() shall return zero and update the
location referenced by
timerid to a
timer_t, which can be passed
to the per-process timer calls. If an error occurs, the function shall return
a value of -1 and set
errno to indicate the error. The value of
timerid is undefined if an error occurs.
The
timer_create() function shall fail if:
- EAGAIN
- The system lacks sufficient signal queuing resources to
honor the request.
- EAGAIN
- The calling process has already created all of the timers
it is allowed by this implementation.
- EINVAL
- The specified clock ID is not defined.
- ENOTSUP
- The implementation does not support the creation of a timer
attached to the CPU-time clock that is specified by clock_id and
associated with a process or thread different from the process or thread
invoking timer_create().
The following sections are informative.
None.
None.
The specified timer facilities may deliver realtime signals (that is, queued
signals) on implementations that support this option. Since realtime
applications cannot afford to lose notifications of asynchronous events, like
timer expirations or asynchronous I/O completions, it must be possible to
ensure that sufficient resources exist to deliver the signal when the event
occurs. In general, this is not a difficulty because there is a one-to-one
correspondence between a request and a subsequent signal generation. If the
request cannot allocate the signal delivery resources, it can fail the call
with an [EAGAIN] error.
Periodic timers are a special case. A single request can generate an unspecified
number of signals. This is not a problem if the requesting process can service
the signals as fast as they are generated, thus making the signal delivery
resources available for delivery of subsequent periodic timer expiration
signals. But, in general, this cannot be assured-processing of periodic timer
signals may "overrun''; that is, subsequent periodic timer expirations
may occur before the currently pending signal has been delivered.
Also, for signals, according to the POSIX.1-1990 standard, if subsequent
occurrences of a pending signal are generated, it is implementation-defined
whether a signal is delivered for each occurrence. This is not adequate for
some realtime applications. So a mechanism is required to allow applications
to detect how many timer expirations were delayed without requiring an
indefinite amount of system resources to store the delayed expirations.
The specified facilities provide for an overrun count. The overrun count is
defined as the number of extra timer expirations that occurred between the
time a timer expiration signal is generated and the time the signal is
delivered. The signal-catching function, if it is concerned with overruns, can
retrieve this count on entry. With this method, a periodic timer only needs
one "signal queuing resource" that can be allocated at the time of
the
timer_create() function call.
A function is defined to retrieve the overrun count so that an application need
not allocate static storage to contain the count, and an implementation need
not update this storage asynchronously on timer expirations. But, for some
high-frequency periodic applications, the overhead of an additional system
call on each timer expiration may be prohibitive. The functions, as defined,
permit an implementation to maintain the overrun count in user space,
associated with the
timerid. The
timer_getoverrun() function can
then be implemented as a macro that uses the
timerid argument (which
may just be a pointer to a user space structure containing the counter) to
locate the overrun count with no system call overhead. Other implementations,
less concerned with this class of applications, can avoid the asynchronous
update of user space by maintaining the count in a system structure at the
cost of the extra system call to obtain it.
The Realtime Signals Extension option supports an application-specific datum
that is delivered to the extended signal handler. This value is explicitly
specified by the application, along with the signal number to be delivered, in
a
sigevent structure. The type of the application-defined value can be
either an integer constant or a pointer. This explicit specification of the
value, as opposed to always sending the timer ID, was selected based on
existing practice.
It is common practice for realtime applications (on non-POSIX systems or
realtime extended POSIX systems) to use the parameters of event handlers as
the case label of a switch statement or as a pointer to an application-defined
data structure. Since
timer_ids are dynamically allocated by the
timer_create() function, they can be used for neither of these
functions without additional application overhead in the signal handler; for
example, to search an array of saved timer IDs to associate the ID with a
constant or application data structure.
None.
clock_getres() ,
timer_delete() ,
timer_getoverrun() , the
Base Definitions volume of IEEE Std 1003.1-2001,
<time.h>
Portions of this text are reprinted and reproduced in electronic form from IEEE
Std 1003.1, 2003 Edition, Standard for Information Technology -- Portable
Operating System Interface (POSIX), The Open Group Base Specifications Issue
6, Copyright (C) 2001-2003 by the Institute of Electrical and Electronics
Engineers, Inc and The Open Group. In the event of any discrepancy between
this version and the original IEEE and The Open Group Standard, the original
IEEE and The Open Group Standard is the referee document. The original
Standard can be obtained online at http://www.opengroup.org/unix/online.html
.
