dg_cpu_id_set(3T) SDK R4.11 dg_cpu_id_set(3T)
NAME
dgcpuidsetinit, dgcpuidsetdestroy, dgcpuidsetaddid,
dgcpuidsetremoveid, dgcpuidsetismember,
dgcpuidsetassignset, dgcpuidsetaddset,
dgcpuidsetremoveset, dgcpuidsethasmembers - manipulate CPU
ID sets
SYNOPSIS
#include <sys/dgcpu.h>
int dgcpuidsetinit(dgcpuidsett *idsetptr);
int dgcpuidsetdestroy(dgcpuidsett *idsetptr);
int dgcpuidsetaddid(dgcpuidsett *idsetptr,
dgcpuidt id);
int dgcpuidsetremoveid(dgcpuidsett *idsetptr,
dgcpuidt id);
int dgcpuidsetismember(dgcpuidsett *idsetptr,
dgcpuidt id);
int dgcpuidsetassignset(dgcpuidsett *destidsetptr,
const dgcpuidsett *sourceidsetptr);
int dgcpuidsetaddset(dgcpuidsett *destidsetptr,
const dgcpuidsett *addidsetptr);
int dgcpuidsetremoveset(dgcpuidsett *destidsetptr,
const dgcpuidsett *removeidsetptr);
int dgcpuidsethasmembers(dgcpuidsett *destidsetptr,
const dgcpuidsett *idsubsetptr);
where:
idsetptr A pointer to a CPU ID set that is being manipulated
by a single CPU id
id A CPU ID that is being added, removed, or tested for
inclusion
destidsetptr A pointer to a CPU ID set that is being manipulated
by another set
sourceidsetptr
A pointer to a CPU ID set that is to be copied into
the destination set
addidsetptr A pointer to a CPU ID set whose IDs are to be added
to the destination set
removeidsetptr
A pointer to a CPU ID set whose IDs are to be removed
from the destination set
idsubsetptr A pointer to a CPU ID set that is being testing for
inclusion
DESCRIPTION
CPU ID sets are opaque collections of CPU IDs. CPU ID sets are
reported by calls to dgcpuinfo() and are used to manipulate the CPU
affinity of LWP groups with calls to dgcpusetaffinity() and
dgcpugetaffinity().
CPU ID sets are properly manipulated by the object-oriented functions
described here. This allows CPU ID sets to accommodate future
machines with larger CPU counts. The use of a bitmask would have
greatly restricted the flexibility of CPU ID sets.
Before a CPU ID set can be used, it must be initialized by a call to
dgcpuidsetinit(). When it is no longer used, it should be
destroyed by a call to dgcpuidsetdestroy(), otherwise a memory
leak might occur. The dgcpuinfoinit() call initializes all CPU id
sets in the passed struct dgcpuinfo.
Typically, an application will use the CPU ID sets returned by
dgcpuinfo() as parameters to the affinity-related calls.
For a more detailed explanation of CPU ID sets, dgcpuinfo(), and
CPU affinity, refer to <sys/dgcpu.h>.
The following functions manipulate CPU ID sets:
dgcpuidsetinit()
Initializes the CPU ID set pointed to by idsetptr to hold the
maximum number of possible CPU IDs on the current system. Upon
successful return, the CPU ID set is initialized to contain no CPU
IDs and is ready for subsequent function calls.
dgcpuidsetdestroy()
Destroys the previously initialized CPU ID set pointed to by
idsetptr. Fails with EINVAL if idsetptr does not point to an
initialized CPU ID set.
dgcpuidsetaddid()
Adds the given id to the CPU ID set pointed to by idsetptr. Fails
with EINVAL if idsetptr does not point to an initialized CPU ID set
or if id is outside the range allowed for the CPU ID set. If id is
already be present in the set, this call will have no effect.
dgcpuidsetremoveid()
Removes the given id from the CPU ID set pointed to by idsetptr.
Fails with EINVAL if idsetptr does not point to an initialized CPU
ID set or if id is outside the range allowed for the CPU ID set. If
id is already not present in the set, this call will have no effect.
dgcpuidsetismember()
Returns 1 if the given id is in the CPU ID set pointed to idsetptr,
and returns 0 if the given id is not in the set. Fails with EINVAL
if idsetptr does not point to an initialized CPU ID set or if id is
outside the range allowed for the CPU ID set.
dgcpuidsetassignset()
Assigns the contents of the CPU ID set pointed to by
sourceidsetptr to the CPU ID set pointed to by destidsetptr.
Fails with EINVAL if either CPU ID set is not initialized.
dgcpuidsetaddset()
Adds all CPU IDs in the CPU ID set pointed to by addidsetptr to
the CPU ID set pointed to by destidsetptr. This is equivalent to
a "set union" operation. Fails with EINVAL if either CPU ID set is
not initialized.
dgcpuidsetremoveset()
Removes all IDs in the CPU ID set pointed to by removeidsetptr
from the CPU ID set pointed to by destidsetptr. This is
equivalent to a "set difference" operation. Fails with EINVAL if
either CPU ID set is not initialized. Note that the destination CPU
ID set need not already contain all IDs in the remove CPU ID set.
dgcpuidsethasmembers()
Returns 1 if all IDs in the CPU ID set pointed to by idsubsetptr
are contained in the CPU ID set pointed to by idsetptr or if the
CPU ID subset is empty; otherwise returns 0 if the subset contains
one or more IDs that are not present in the first set. Fails with
EINVAL if either CPU ID set is not initialized.
DIAGNOSTICS
Return Value
If successful, dgcpuidsetinit(), dgcpuidsetdestroy(),
dgcpuidsetaddid(), dgcpuidsetremoveid(),
dgcpuidsetassignset(), dgcpuidsetaddset(), and
dgcpuidsetremoveset() return 0. Otherwise, they return -1 and
set errno to indicate the error.
If successful, dgcpuidsetismember() and
dgcpuidsethasmembers() return 0 or 1. Otherwise, they return -1
and set errno to indicate the error.
Errors
For each of the following conditions, dgcpuidsetdestroy(),
dgcpuidsetaddid(), dgcpuidsetremoveid(),
dgcpuidsetismember(), dgcpuidsetassignset,
dgcpuidsetaddset(), dgcpuidsetremoveset(), and
dgcpuidsethasmembers() 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, destidsetptr, sourceidsetptr,
addidsetptr, removeidsetptr, or idsubsetptr has not
been initialized by a previous call to dgcpuidsetinit()
or has been corrupted.
For each of the following conditions, dgcpuidsetaddid(),
dgcpuidsetremoveid(), and dgcpuidsetismember() return -1
and set errno to the corresponding value:
[EINVAL] The value given by id is outside the range of allowed CPU
IDs for the CPU ID set.
SEE ALSO
dgcpuinfoinit(3T), dgcpuinfodestroy(3T), dgcpuinfo(3T),
dgcpuaffinityattrsetcpuidset(3T),
dgcpuaffinityattrgetcpuidset(3T), dgcpusetaffinity(3T),
dgcpugetaffinity(3T), 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, dgcpuidsetinit() always succeeds and return 0. In the
future, it may need to allocate memory, which could result in an
ENOMEM failure.
Licensed material--property of copyright holder(s)