SCHEDCTL_INIT(3C) Standard C Library Functions SCHEDCTL_INIT(3C)
NAME
schedctl_init, schedctl_lookup, schedctl_exit, schedctl_start,
schedctl_stop - preemption control
SYNOPSIS
cc [
flag... ]
file... [
library... ]
#include <schedctl.h>
schedctl_t *schedctl_init(
void);
schedctl_t *schedctl_lookup(
void);
void schedctl_exit(
void);
void schedctl_start(
schedctl_t *ptr);
void schedctl_stop(
schedctl_t *ptr);
DESCRIPTION
These functions provide limited control over the scheduling of a
thread (see
threads(7)). They allow a running thread to give a hint
to the kernel that preemptions of that thread should be avoided. The
most likely use for these functions is to block preemption while
holding a spinlock. Improper use of this facility, including attempts
to block preemption for sustained periods of time, may result in
reduced performance.
The
schedctl_init() function initializes preemption control for the
calling thread and returns a pointer used to refer to the data. If
schedctl_init() is called more than once by the same thread, the most
recently returned pointer is the only valid one.
The
schedctl_lookup() function returns the currently allocated
preemption control data associated with the calling thread that was
previously returned by
schedctl_init(). This can be useful in
programs where it is difficult to maintain local state for each
thread.
The
schedctl_exit() function removes the preemption control data
associated with the calling thread.
The
schedctl_start() macro gives a hint to the kernel scheduler that
preemption should be avoided on the current thread. The pointer
passed to the macro must be the same as the pointer returned by the
call to
schedctl_init() by the current thread. The behavior of the
program when other values are passed is undefined.
The
schedctl_stop() macro removes the hint that was set by
schedctl_start(). As with
schedctl_start(), the pointer passed to the
macro must be the same as the pointer returned by the call to
schedctl_init() by the current thread.
The
schedctl_start() and
schedctl_stop() macros are intended to be
used to bracket short critical sections, such as the time spent
holding a spinlock. Other uses, including the failure to call
schedctl_stop() soon after calling
schedctl_start(), might result in
poor performance.
RETURN VALUES
The
schedctl_init() function returns a pointer to a
schedctl_t structure if the initialization was successful, or
NULL otherwise.
The
schedctl_lookup() function returns a pointer to a
schedctl_t structure if the data for that thread was found, or
NULL otherwise.
ERRORS
No errors are returned.
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Stable |
+--------------------+-----------------+
|MT-Level | MT-Safe |
+--------------------+-----------------+
SEE ALSO
priocntl(1),
exec(2),
fork(2),
priocntl(2),
attributes(7),
threads(7)NOTES
Preemption control is intended for use by threads belonging to the
time-sharing (TS), interactive (IA), fair-share (FSS), and fixed-
priority (FX) scheduling classes. If used by threads in other
scheduling classes, such as real-time (RT), no errors will be
returned but
schedctl_start() and
schedctl_stop() will not have any
effect.
The data used for preemption control are not copied in the child of a
fork(2). Thus, if a process containing threads using preemption
control calls
fork and the child does not immediately call
exec(2),
each thread in the child must call
schedctl_init() again prior to any
future uses of
schedctl_start() and
schedctl_stop(). Failure to do so
will result in undefined behavior.
May 28, 2003 SCHEDCTL_INIT(3C)
