ra_attach Subroutine

Purpose

Attaches a work component to a resource.

Library

Standard C library (libc.a)

Syntax

#include <sys/rset.h>
int ra_attach(rstype1, rsid1, rstype2, rsid2, flags)
rstype_t rstype1, rstype2;
rsid_t rsid1, rsid2;
unsigned int flags;

Description

The ra_attach subroutine attaches a work component specified by the rstype1 and rsid1 parameters to the resource specified by the rstype2 and rsid2 parameters.

Parameters

Item Description
rstype1 Specifies the type of work component to be attached to the resource specified by rstype2/rsid2. The rstype1 parameter must be one of the following defined in rset.h.
R_PROCESS
Existing process
R_THREAD
Existing kernel thread
R_FILDES
File identified by an open file descriptor
R_SHM
Shared memory segment identified by shared memory ID
R_SUBRANGE
Attachment to a memory range within a work component
rsid1 Specifies the work component associated with the rstype1 parameter. The rsid1 parameter must be one of the following:
Process ID (for rstype1 of R_PROCESS)
Set the rsid_t at_pid field to the desired process ID.
Kernel thread ID (for rstype1 of R_THREAD)
Set the rsid_t.at_tid field to the desired kernel thread ID.
Open file descriptor (for rstype1 of R_FILDES)
Set the rsid_t at_fd field to the desired file descriptor.
Shared memory segment (for rstype of R_SHM)
Set the rsid_t at_shmid field to the desired shared memory ID.
Pointer to a subrange_t struct (for rstype of R_SUBRANGE)
Set the rsid_t at_subbrange field to the address of a subrange_t struct. Set the subrange_t struct su_offset, su_length, su_rstype, and su_rsid fields. The other fields in the subrange_t struct are ignored. The memory allocation policy is taken from the flags parameter, not the su_policy field.

Set the subrange_t su_rstype field to R_PROCMEM and su_rsid.at_pid field to RS_MYSELF to attach to a memory range in the user process. Set the subrange_t su_offset field to the starting address of the range in the process. Set the subrange_t su_length field to the length of the range in the process.

Note: The subrange_t su_offset and su_length fields must be a multiple of 4 KB. For optimum performance, the fields must be the multiple of the page size backing the memory range. The page size used to back a memory range can be obtained using the vmgetinfo subroutine specifying the VM_PAGE_INFO command parameter.
rstype2 Specifies the type of the resource to be attached to the work component. The rstype2 parameter must be one of the following defined in rset.h.
R_RSET
Resource set attachment
R_SRADID
SRADID attachment
rsid2 Specifies the resource associated with the rstype2 parameter. The rsid2 parameter must be one of the following:
Resource set (for rstype2 of R_RSET)
Set the rsid_t at_rset field to the desired resource set.
SRADID (Scheduler Resource Allocation Domain Identifier for rstype2 of R_SRADID)
Set the rsid_t at_sradid field to the desired sradid. An SRADID may only be attached to a thread or to a memory range. An at_sradid value of SRADID_ANY may be specified on memory range attachments to indicate a memory affinity preference for all memory in the partition.
flags Specifies memory allocation and other attachment options:
P_DEFAULT
Default memory allocation policy
P_FIRST_TOUCH
First access memory allocation policy
P_BALANCED
Balanced memory allocation policy
R_MIGRATE_ASYNC
Asynchronously migrate physical memory in the address range (for rstype1 of R_SHM or R_SUBRANGE)
R_MIGRATE_SYNC
Synchronously migrate physical memory in the address range (for rstype1 of R_SHM or R_SUBRANGE)
R_ATTACH_STRSET
Process is to be scheduled with a single-threaded policy, only on one hardware thread per physical processor (for rstype1 of R_PROCESS).

Return Values

If successful, a value of 0 is returned. If unsuccessful, a value of -1 is returned and the errno global variable is set to indicate the error.

Error Codes

Item Description
EINVAL One of the following occurred:
  • The flags parameter contains an invalid value.
  • The rstype1 or rstype2 parameter contains an invalid type identifier.
ENODEV One of the following occurred:
  • The resource set specified by the rstype2 and rsid2 parameters does not contain any available processors.
  • An invalid rsid2 SRADID is specified.
ENOTSUP One of the following occurred:
  • An attempt to attach an SRADID is made and ENHANCED_AFFINITY is disabled.
  • An attempt to attach an SRADID to a file is made.
  • An R_SUBRANGE request with su_rstype R_PROCMEM is made and the su_rsid.at_pid field is not RS_MYSELF.
ESRCH A work component specified by the rstype1 and rsid1 parameters does not exist.
EPERM One of the following occurred:
  • rstype2 specified R_RSET and calling process has neither root authority nor CAP_NUMA_ATTACH attachment privilege. j
  • rstype2 specified R_RSET and calling process has neither root authority nor the same effective user ID as the process identified by the rstype1 and rsid1 parameters.
  • rstype2 specified R_RSET or R_SRADID and the process or thread work component specified by the rstype1 and rsid1 parameters has one or more threads with a bindprocessor binding.
  • rstype1 and rsid1 parameters specified a process and rstype2 and rsid2 parameters specified a resource set. The processors in the rset are not included in the process’s partition resource set or a thread in the specified process has a resource set attachment that is not a subset of the rstype1/rsid1 resource set.
  • rstype2 specified R_SRADID attachment to a memory range that has a resource set attachment.