dg_cpu_affinity_attr(3T) DG/UX 5.4R3.00 dg_cpu_affinity_attr(3T)
NAME
dgcpuaffinityattrinit, dgcpuaffinityattrdestroy,
dgcpuaffinityattrsetcpuidset,
dgcpuaffinityattrgetcpuidset,
dgcpuaffinityattrsetminimumlevel,
dgcpuaffinityattrgetminimumlevel - CPU affinity attributes
objects
SYNOPSIS
#include <sys/dgcpu.h>
int dgcpuaffinityattrinit(dgcpuaffinityattrt *attrptr);
int dgcpuaffinityattrdestroy(dgcpuaffinityattrt *attrptr);
int dgcpuaffinityattrsetcpuidset(
dgcpuaffinityattrt *attrptr,
const dgcpuidsett *idsetptr);
int dgcpuaffinityattrgetcpuidset(
dgcpuaffinityattrt *attrptr,
dgcpuidsett *idsetptr);
int dgcpuaffinityattrsetminimumlevel(
dgcpuaffinityattrt *attrptr,
int minlevel);
int dgcpuaffinityattrgetminimumlevel(
dgcpuaffinityattrt *attrptr,
int *minlevelptr);
where:
attrptr A pointer to a CPU affinity attributes object
idsetptr A pointer to a CPU ID set
minlevel The minimum allowed level attribute
minlevelptr
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
dgcpusetaffinity() and dgcpugetaffinity(). Affinity attributes
are provided to specify or retrieve the allowed CPU ID set and
minimum allowed migration level for LWP groups. Refer to
<sys/dgcpu.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.
Licensed material--property of copyright holder(s) 1
dg_cpu_affinity_attr(3T) DG/UX 5.4R3.00 dg_cpu_affinity_attr(3T)
Before a CPU affinity attributes object can be used, it must be
initialized by a call to dgcpuaffinityattrinit(). After it has
been initialized, individual attributes are specified by other
object-oriented calls, then the attributes object is passed to a call
to dgcpusetaffinity(). 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
dgcpuaffinityattrdestroy(). If desired, the attributes object
need not be destroyed; it can instead be used in subsequent calls to
dgcpusetaffinity() for other LWP groups.
Similarly, the affinity attributes for an existing LWP group can be
retrieved by a call to dgcpugetaffinity().
The following functions manipulate CPU affinity attributes objects:
dgcpuaffinityattrinit()
This function initializes the CPU affinity attributes object pointed
to by attrptr 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 DGCPUAFFINITYDEFAULTMINIMUMLEVEL, whose
meaning depends on the scheduling policy of the affected LWP group.
dgcpuaffinityattrdestroy()
This function destroys the CPU affinity attributes object pointed to
by attrptr. The attributes object should have been initialized by a
previous call to dgcpuaffinityattrinit(). 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.
dgcpuaffinityattrsetcpuidset()
This function sets the allowed CPU ID set attribute in the affinity
attributes object pointed to by attrptr to the CPU ID set pointed to
by idsetptr. 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 dgcpuinfo(). However,
arbitrary CPU ID sets can also be constructed and passed into this
function.
dgcpuaffinityattrgetcpuidset()
This function retrieves the allowed CPU ID set attribute from the
affinity attributes object pointed to by attrptr and stores it into
the location pointed to by idsetptr.
dgcpuaffinityattrsetminimumlevel()
This function sets the allowed minimum migration level attribute in
the affinity attributes object pointed to by attrptr to the level
given by minlevel. 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 DGCPUAFFINITYDEFAULTMINIMUMLEVEL indicates
Licensed material--property of copyright holder(s) 2
dg_cpu_affinity_attr(3T) DG/UX 5.4R3.00 dg_cpu_affinity_attr(3T)
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).
dgcpuaffinityattrgetminimumlevel()
This function retrieves the allowed minimum migration level attribute
from the affinity attributes object pointed to by attrptr and stores
it into the location pointed to by minlevelptr.
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, dgcpuaffinityattrdestroy(),
dgcpuaffinityattrsetcpuidset(),
dgcpuaffinityattrgetcpuidset(),
dgcpuaffinityattrsetminimumlevel(), and
dgcpuaffinityattrgetminimumlevel() 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 attrptr has not been initialized by a
previous call to dgcpuaffinityattrinit() or has been
corrupted.
For each of the following conditions,
dgcpuaffinityattrsetcpuidset() and
dgcpuaffinityattrgetcpuidset() 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
idsetptr has not been initialized by a previous call to
dgcpuidsetinit() or has been corrupted.
For each of the following conditions,
dgcpuaffinityattrsetminimumlevel() returns -1 and sets errno to
the corresponding value:
[EINVAL] The value given by minlevel is not
DGCPUAFFINITYDEFAULTMINIMUMLEVEL or is greater than
(DGCPUMAXLEVELS-1).
SEE ALSO
dgcpusetaffinity(3T), dgcpugetaffinity(3T), dgcpuinfo(3T),
dgcpuidsetinit(3T), dgpthreadgroupcreate(3T).
dgpthreadgroupgetlwpgroupid(3T), dglwpinfo(2), threads(5).
Licensed material--property of copyright holder(s) 3
dg_cpu_affinity_attr(3T) DG/UX 5.4R3.00 dg_cpu_affinity_attr(3T)
NOTES
An application must link with -lthread in order to gain access to
these functions. However, the application need not use threads.
Currently, dgcpuaffinityattrinit() 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) 4