dg_mem_set_affinity(3T) SDK R4.11 dg_mem_set_affinity(3T)
NAME
dgmemsetaffinity - set memory placement characteristics
SYNOPSIS
#include <sys/dgmemaffinity.h>
int dgmemsetaffinity (version,
selector,
selectorvalue1,
selectorvalue2,
attrptr)
long version;
long selector;
long selectorvalue1;
long selectorvalue2;
dgmemaffinityattrt * attrptr;
where:
version
An integer specifying the version number of the call. This
argument should be set to DG_MEM_SET_AFFINITY_CURRENT_VERSION.
selector
An integer value that indicates to the operating system how it
should interpret the selector values.
selectorvalue1, selectorvalue2
Depending on the value of <selector>, these values specify the
memory object or objects for which the caller wishes to set
affinity properties.
attrptr
A pointer to a memory affinity attributes structure.
dgmemsetaffinity() will apply the affinity properties
described in this structure to the target object.
DESCRIPTION
The dgmemsetaffinity() call changes the memory affinity attributes
of the object or objects specified by the selector data. The DG/UX
system uses memory affinity attributes to determine the physical
location of memory allocated by and for user processes. Programs may
use the dgmemsetaffinity() call to target memory allocations and
cause the operatin system to place memory "near" the program's
executing threads. Specifically, a program may specify a CPU or a
set of CPUs near which it would like the operating system to place
its memory. It may then affine its threads to the same location.
See dgcpusetaffinity(3T) for information on thread affinity.
In the context of memory placement, the terms "near" and "far" refer
to the latency involved in accessing physical memory, where access to
"near" memory takes less time than accesses to "far" memory. On a
system with a Uniform Memory Access (UMA) architecture, access to all
system memory incurs the same latency, so memory affinity is not an
important programming consideration. On a system with a Non-Uniform
Memory Access (NUMA) architecture, not all memory accesses are of
equal cost, and a program may see a performance benefit from
controlling the physical placement of the memory it allocates.
The memory affinity attributes themselves are specified in the
affinity structure, a reference to which is passed to the
dgmemsetaffinity() call in the attrptr argument. The affinity
attribute structure is opaque to programs. It must be initialized
with the dgmemaffinityattrinit(3T) call. The CPU sets to which
memory will be affined may be set in the attributes structure using
the dgmemsetcpuidset(3T) call. CPU sets are manipulated using
the standard interfaces that apply to CPU affinity. See
dgcpuidsetinit(3T), et. al.
The version argument must specify which version of the system call is
to be used. A program may ensure it is using the most recent version
by specifying DG_MEM_SET_AFFINITY_CURRENT_VERSION for the version
argument. This is the recommended value for all programs.
The selector argument specifies the memory object to which affinity
properties are to be applied. In turn, the value of selector
determines the meaning and valid range of values for the
selectorvalue1 and selectorvalue2 arguments.
Currently only one value of selector is supported:
DG_MEM_SELECTOR_MY_PID
This value instructs the operating system to apply the
affinity properties to the address space of the calling
process. When this selector is specified, selectorvalue1
must contain an address in the caller's address space, and
selectorvalue2 must contain a length in bytes. The
affinity attributes will be associated with memory
beginning at the address specified by selectorvalue1 and
continuing for the extent specified by selectorvalue2 .
selectorvalue1 must be aligned to a memory page boundary.
selectorvalue2 must be a whole number of memory pages.
While new memory will be placed according to the affinity
specified by the dgmemsetaffinity() call, memory that
has already been allocated and lies within the specified
range will not be moved to reflect the new affinity
properties.
The per-process affinity properties are inherited by child
processes created by the fork(2) system call.
Multiple calls to dgmemsetaffinity() that specify the same memory
object are allowed. The latest call overrides the affinity set by a
previous call.
ACCESS CONTROL
The caller of dgmemsetaffinity() must have permission to change
the attributes of the underlying memory object. In the case of
DG_MEM_SEoperating system, this permission is implicit.
RETURN VALUE
If successful, dgmemsetaffinity() returns 0. Otherwise, it
returns -1 and sets errno to indicate the error.
DIAGNOSTICS
If any of the following conditions occur, the dgmemsetaffinity()
system call shall return -1 and set errno to the corresponding value:
EINVAL The value specified by <version> or <selector> is not
supported.
EINVAL Invalid affinity attributes have been specified. This
occurs when DG/UX detects that the the affinity attributes
referenced by <attr_ptr> have not been initialized by a
previous call to dg_cpu_affinity_attr_init() or have been
corrupted.
EACCES The caller does not have permission to change the
attributes of an underlying memory object.
ENOMEM The kernel could not allocate memory for an internal data
structure.
When selector is DG_MEM_SELECTOR_MY_PID, the following error codes
may be returned:
EINVAL selectorvalue1 is not aligned to a memory page boundary.
EINVAL selectorvalue2 is not greater than zero or is not a whole
number of pages.
SEE ALSO
dgmemaffinityattrinit(3T), dgcpusetaffinity(3T),
dgmemgetcpuidset(3T), dgmemsetcpuidset(3T),
dgcpuidsetinit(3T)
NOTE
An application must link with -lthread in order to gain access to
this function. However, the application need not use threads.
Licensed material--property of copyright holder(s)