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)