dg_cpu_id_set(3T) DG/UX 5.4R3.00 dg_cpu_id_set(3T)
NAME
dg_cpu_id_set_init, dg_cpu_id_set_destroy, dg_cpu_id_set_add_id,
dg_cpu_id_set_remove_id, dg_cpu_id_set_is_member,
dg_cpu_id_set_assign_set, dg_cpu_id_set_add_set,
dg_cpu_id_set_remove_set, dg_cpu_id_set_has_members - manipulate CPU
ID sets
SYNOPSIS
#include <sys/dg_cpu.h>
int dg_cpu_id_set_init(dg_cpu_id_set_t *id_set_ptr);
int dg_cpu_id_set_destroy(dg_cpu_id_set_t *id_set_ptr);
int dg_cpu_id_set_add_id(dg_cpu_id_set_t *id_set_ptr,
dg_cpu_id_t id);
int dg_cpu_id_set_remove_id(dg_cpu_id_set_t *id_set_ptr,
dg_cpu_id_t id);
int dg_cpu_id_set_is_member(dg_cpu_id_set_t *id_set_ptr,
dg_cpu_id_t id);
int dg_cpu_id_set_assign_set(dg_cpu_id_set_t *dest_id_set_ptr,
const dg_cpu_id_set_t *source_id_set_ptr);
int dg_cpu_id_set_add_set(dg_cpu_id_set_t *dest_id_set_ptr,
const dg_cpu_id_set_t *add_id_set_ptr);
int dg_cpu_id_set_remove_set(dg_cpu_id_set_t *dest_id_set_ptr,
const dg_cpu_id_set_t *remove_id_set_ptr);
int dg_cpu_id_set_has_members(dg_cpu_id_set_t *dest_id_set_ptr,
const dg_cpu_id_set_t *id_subset_ptr);
where:
id_set_ptr 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
dest_id_set_ptr A pointer to a CPU ID set that is being manipulated
by another set
source_id_set_ptr
A pointer to a CPU ID set that is to be copied into
the destination set
add_id_set_ptr A pointer to a CPU ID set whose IDs are to be added
to the destination set
remove_id_set_ptr
A pointer to a CPU ID set whose IDs are to be removed
from the destination set
id_subset_ptr A pointer to a CPU ID set that is being testing for
inclusion
Licensed material--property of copyright holder(s) 1
dg_cpu_id_set(3T) DG/UX 5.4R3.00 dg_cpu_id_set(3T)
DESCRIPTION
CPU ID sets are opaque collections of CPU IDs. CPU ID sets are
reported by calls to dg_cpu_info() and are used to manipulate the CPU
affinity of LWP groups with calls to dg_cpu_set_affinity() and
dg_cpu_get_affinity().
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
dg_cpu_id_set_init(). When it is no longer used, it should be
destroyed by a call to dg_cpu_id_set_destroy(), otherwise a memory
leak might occur. The dg_cpu_info_init() call initializes all CPU id
sets in the passed struct dg_cpu_info.
Typically, an application will use the CPU ID sets returned by
dg_cpu_info() as parameters to the affinity-related calls.
For a more detailed explanation of CPU ID sets, dg_cpu_info(), and
CPU affinity, refer to <sys/dg_cpu.h>.
The following functions manipulate CPU ID sets:
dg_cpu_id_set_init()
Initializes the CPU ID set pointed to by id_set_ptr 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.
dg_cpu_id_set_destroy()
Destroys the previously initialized CPU ID set pointed to by
id_set_ptr. Fails with EINVAL if id_set_ptr does not point to an
initialized CPU ID set.
dg_cpu_id_set_add_id()
Adds the given id to the CPU ID set pointed to by id_set_ptr. Fails
with EINVAL if id_set_ptr 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.
dg_cpu_id_set_remove_id()
Removes the given id from the CPU ID set pointed to by id_set_ptr.
Fails with EINVAL if id_set_ptr 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.
dg_cpu_id_set_is_member()
Returns 1 if the given id is in the CPU ID set pointed to id_set_ptr,
and returns 0 if the given id is not in the set. Fails with EINVAL
if id_set_ptr does not point to an initialized CPU ID set or if id is
outside the range allowed for the CPU ID set.
Licensed material--property of copyright holder(s) 2
dg_cpu_id_set(3T) DG/UX 5.4R3.00 dg_cpu_id_set(3T)
dg_cpu_id_set_assign_set()
Assigns the contents of the CPU ID set pointed to by
source_id_set_ptr to the CPU ID set pointed to by dest_id_set_ptr.
Fails with EINVAL if either CPU ID set is not initialized.
dg_cpu_id_set_add_set()
Adds all CPU IDs in the CPU ID set pointed to by add_id_set_ptr to
the CPU ID set pointed to by dest_id_set_ptr. This is equivalent to
a "set union" operation. Fails with EINVAL if either CPU ID set is
not initialized.
dg_cpu_id_set_remove_set()
Removes all IDs in the CPU ID set pointed to by remove_id_set_ptr
from the CPU ID set pointed to by dest_id_set_ptr. 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.
dg_cpu_id_set_has_members()
Returns 1 if all IDs in the CPU ID set pointed to by id_subset_ptr
are contained in the CPU ID set pointed to by id_set_ptr 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, dg_cpu_id_set_init(), dg_cpu_id_set_destroy(),
dg_cpu_id_set_add_id(), dg_cpu_id_set_remove_id(),
dg_cpu_id_set_assign_set(), dg_cpu_id_set_add_set(), and
dg_cpu_id_set_remove_set() return 0. Otherwise, they return -1 and
set errno to indicate the error.
If successful, dg_cpu_id_set_is_member() and
dg_cpu_id_set_has_members() return 0 or 1. Otherwise, they return -1
and set errno to indicate the error.
Errors
For each of the following conditions, dg_cpu_id_set_destroy(),
dg_cpu_id_set_add_id(), dg_cpu_id_set_remove_id(),
dg_cpu_id_set_is_member(), dg_cpu_id_set_assign_set,
dg_cpu_id_set_add_set(), dg_cpu_id_set_remove_set(), and
dg_cpu_id_set_has_members() 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, dest_id_set_ptr, source_id_set_ptr,
add_id_set_ptr, remove_id_set_ptr, or id_subset_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_id_set_add_id(),
dg_cpu_id_set_remove_id(), and dg_cpu_id_set_is_member() return -1
Licensed material--property of copyright holder(s) 3
dg_cpu_id_set(3T) DG/UX 5.4R3.00 dg_cpu_id_set(3T)
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
dg_cpu_info_init(3T), dg_cpu_info_destroy(3T), dg_cpu_info(3T),
dg_cpu_affinity_attr_set_cpu_id_set(3T),
dg_cpu_affinity_attr_get_cpu_id_set(3T), dg_cpu_set_affinity(3T),
dg_cpu_get_affinity(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, dg_cpu_id_set_init() 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) 4