dg_cpu_affinity_attr(3T) DG/UX R4.11MU05 dg_cpu_affinity_attr(3T)
NAME
dg_cpu_affinity_attr_init, dg_cpu_affinity_attr_destroy,
dg_cpu_affinity_attr_set_cpu_id_set,
dg_cpu_affinity_attr_get_cpu_id_set,
dg_cpu_affinity_attr_set_minimum_level,
dg_cpu_affinity_attr_get_minimum_level - CPU affinity attributes
objects
SYNOPSIS
#include <sys/dg_cpu.h>
int dg_cpu_affinity_attr_init(dg_cpu_affinity_attr_t *attr_ptr);
int dg_cpu_affinity_attr_destroy(dg_cpu_affinity_attr_t *attr_ptr);
int dg_cpu_affinity_attr_set_cpu_id_set(
dg_cpu_affinity_attr_t *attr_ptr,
const dg_cpu_id_set_t *id_set_ptr);
int dg_cpu_affinity_attr_get_cpu_id_set(
dg_cpu_affinity_attr_t *attr_ptr,
dg_cpu_id_set_t *id_set_ptr);
int dg_cpu_affinity_attr_set_minimum_level(
dg_cpu_affinity_attr_t *attr_ptr,
int min_level);
int dg_cpu_affinity_attr_get_minimum_level(
dg_cpu_affinity_attr_t *attr_ptr,
int *min_level_ptr);
where:
attr_ptr A pointer to a CPU affinity attributes object
id_set_ptr A pointer to a CPU ID set
min_level The minimum allowed level attribute
min_level_ptr
A pointer to a location to receive the minimum allowed
level attribute
DESCRIPTION
DG CPU affinity attributes objects are opaque collections of CPU
affinity attributes that are used to manually set or retrieve the
affinity parameters for LWP groups using calls to
dg_cpu_set_affinity() and dg_cpu_get_affinity(). Affinity attributes
are provided to specify or retrieve the allowed CPU ID set and
minimum allowed migration level for LWP groups. Refer to
<sys/dg_cpu.h> for a detailed discription of CPU affinity and these
attributes.
CPU affinity attributes objects are manipulated only by object-
oriented functions described here and in other man pages list below.
The use of opaque attributes objects provides a clean isolation of
the configurable aspects of CPU affinity and an extensible mechanism
for adding future affinity attributes.
Before a CPU affinity attributes object can be used, it must be
initialized by a call to dg_cpu_affinity_attr_init(). After it has
been initialized, individual attributes are specified by other
object-oriented calls, then the attributes object is passed to a call
to dg_cpu_set_affinity(). Upon return from such a call the
attributes object is no longer associated with the affected LWP
groups, and can be destroyed by a call to
dg_cpu_affinity_attr_destroy(). If desired, the attributes object
need not be destroyed; it can instead be used in subsequent calls to
dg_cpu_set_affinity() for other LWP groups.
Similarly, the affinity attributes for an existing LWP group can be
retrieved by a call to dg_cpu_get_affinity().
The following functions manipulate CPU affinity attributes objects:
dg_cpu_affinity_attr_init()
This function initializes the CPU affinity attributes object pointed
to by attr_ptr with the default values for all CPU affinity
attributes. The default allowed CPU ID set contains all possible CPU
IDs for the underlying machine. The default minimum allowed
migration level is DG_CPU_AFFINITY_DEFAULT_MINIMUM_LEVEL, whose
meaning depends on the scheduling policy of the affected LWP group.
dg_cpu_affinity_attr_destroy()
This function destroys the CPU affinity attributes object pointed to
by attr_ptr. The attributes object should have been initialized by a
previous call to dg_cpu_affinity_attr_init(). The behavior of using
the attributes object after it has been destroyed is undefined. If
DG/UX detects that an attributes object is uninitialized or
destroyed, it will cause the using function to fail with EINVAL.
dg_cpu_affinity_attr_set_cpu_id_set()
This function sets the allowed CPU ID set attribute in the affinity
attributes object pointed to by attr_ptr to the CPU ID set pointed to
by id_set_ptr. The allowed CPU ID set determines the CPUs on which
affected LWP groups are allowed to run. Typically, the caller uses a
CPU ID set returned by a previous call to dg_cpu_info(). However,
arbitrary CPU ID sets can also be constructed and passed into this
function.
dg_cpu_affinity_attr_get_cpu_id_set()
This function retrieves the allowed CPU ID set attribute from the
affinity attributes object pointed to by attr_ptr and stores it into
the location pointed to by id_set_ptr.
dg_cpu_affinity_attr_set_minimum_level()
This function sets the allowed minimum migration level attribute in
the affinity attributes object pointed to by attr_ptr to the level
given by min_level. The minimum allowed level determines the level
in the CPU hierarchy down to which affected LWP groups may migrate,
where level 0 is the level of an individual CPU. Lower allowed
levels imply better CPU affinity at the expense of response time.
The default value DG_CPU_AFFINITY_DEFAULT_MINIMUM_LEVEL indicates
that the minimum allowed level should be chosen based on the
scheduling policy of the affected LWP group; in particular,
timesharing LWP groups are allowed to migrate down to level zero
(optimizing throughput), whereas realtime LWP groups are not allowed
to migrate below the root of the CPU hierarchy (optimizing response
time).
dg_cpu_affinity_attr_get_minimum_level()
This function retrieves the allowed minimum migration level attribute
from the affinity attributes object pointed to by attr_ptr and stores
it into the location pointed to by min_level_ptr.
DIAGNOSTICS
Returns
If successful, these functions return 0. Otherwise they return -1
and set errno to indicate the error.
Errors
For each of the following conditions, dg_cpu_affinity_attr_destroy(),
dg_cpu_affinity_attr_set_cpu_id_set(),
dg_cpu_affinity_attr_get_cpu_id_set(),
dg_cpu_affinity_attr_set_minimum_level(), and
dg_cpu_affinity_attr_get_minimum_level() return -1 and set errno to
the corresponding value:
[EINVAL] An invalid attributes object has been specified. This
occurs when DG/UX has detected that the attributes object
pointed to by attr_ptr has not been initialized by a
previous call to dg_cpu_affinity_attr_init() or has been
corrupted.
For each of the following conditions,
dg_cpu_affinity_attr_set_cpu_id_set() and
dg_cpu_affinity_attr_get_cpu_id_set() return -1 and set errno to the
corresponding value:
[EINVAL] An invalid CPU ID set has been specified. This occurs when
DG/UX has detected that the CPU ID set pointed to by
id_set_ptr has not been initialized by a previous call to
dg_cpu_id_set_init() or has been corrupted.
For each of the following conditions,
dg_cpu_affinity_attr_set_minimum_level() returns -1 and sets errno to
the corresponding value:
[EINVAL] The value given by min_level is not
DG_CPU_AFFINITY_DEFAULT_MINIMUM_LEVEL or is greater than
(DG_CPU_MAX_LEVELS-1).
SEE ALSO
dg_cpu_set_affinity(3T), dg_cpu_get_affinity(3T), dg_cpu_info(3T),
dg_cpu_id_set_init(3T), dg_pthread_group_create(3T).
dg_pthread_group_get_lwp_group_id(3T), dg_lwp_info(2), threads(5).
NOTES
An application must link with -lthread in order to gain access to
these functions. However, the application need not use threads.
Currently, dg_cpu_affinity_attr_init() always succeeds and returns 0.
In the future, it may need to allocate memory, which could result in
an ENOMEM failure.
Attributes objects are also provided for threads, mutexes, condition
variables, and DG thread groups. While the attributes vary from
entity to entity, the style of the interfaces is consistent.
Licensed material--property of copyright holder(s)