ra_shmget and ra_shmgetv Subroutines

Purpose

Gets a shared memory segment and attaches it to a resource.

Library

Standard C library (libc.a)

Syntax

#include <sys/rset.h>
#include <sys/shm.h>

int ra_shmget(key, size, flags, rstype, rsid, att_flags)
key_t key;
size64_t size;
int flags;
rstype_t rstype;
rsid_t rsid;
unsigned int att_flags;
int ra_shmgetv(key, size, flags, rangecnt, rangevec)
key_t key;
size64_t size;
int flags;
int rangecnt;
subrange_t *rangevec;

Parameters

As per existing shmget usage, plus the following new parameters:

Item Description
rstype Specifies the type of resource the new shared memory segment is to be attached to. This parameter must have one of the following values:
  • R_RSET: Resource set attachment
  • R_SRADID: SRADID attachment
rsid Identifies the resource to which the new shared memory segment is to be attached. All attachments are advisory. If memory cannot be allocated from the RAD(s) specified by rstype/rsid parameters, memory is allocated from any RAD in the system that has memory available.
  • Resource set handle (for rstype R_RSET): set the rsid.at field to the desired resource set.
  • SRADID (Scheduler Resource Allocation Domain Identifier for rstype R_SRADID): set the rsid.at_sradid to the desired sradid.
att_flags Specifies an advisory memory allocation policy that is to be applied to the new shared memory segment. This parameter must have one of the following values defined in sys/rset.h:
  • P_FIRST_TOUCH: First Access memory policy. Memory is allocated from the current node, the RAD of the processor on which it is accessed for the first time, if this RAD is in the attachment resource set. If it is not, memory is allocated form an undefined RAD in the attachment resource set.
  • P_BALANCED: Balanced memory policy. Memory is allocated in a round robin manner across the RADs contained in the attachment resource set.
  • P_DEFAULT: Default memory placement policy.
rangecnt Specifies the number of subrange_t structures pointed to by rangevec.
rangevec Specifies a pointer to an array of subrange_t structures describing the desired subrange attachments.

Description

The ra_shmget subroutine returns the shared memory identifier associated with the specified key, size and flags parameters, attaching it to the resource set (R_RSET) specified by rstype, and rsid. The ra_shmget subroutine supports the sradid attachments. If the shared memory is attached to a set of physical resources involving multiple resource allocation domains (RADs), its memory allocation is distributed among these RADs according to att_flags. In an R_RSET type attachment, the processors specified in the input resource set are used for memory associativity; the resource set memory regions are ignored. All memory allocation attachments and policies are advisory.

If the new shared memory segment is to be attached in its entirety to a resource (that is, no subranges are involved), then the rstype or rsid parameters identify the memory attachment.

The ra_shmgetv subroutine is similar to the ra_shmget subroutine, and allows multiple subranges of the new shared memory segment to be attached to multiple resources in a single ra_shmgetv call. The rangevec argument is a pointer to an array of subrange_t structures describing the attachments to be performed. The rangecnt argument specifies the number of subrange_t structures pointed to by rangevec. All unused subrange_t structure fields, including those marked as reserved, must be initialized to the value of 0. Although it is not failing, the behavior with overlapping subranges is undefined.

Return Values

On successful completion, a shared memory identifier is returned. Otherwise, a value of -1 is returned and the errno global variable is set to indicate the error.

Error Codes

As per existing shmget usage, plus the following errors:

Item Description
EINVAL One of the following conditions is true:
  • rstype contains an invalid type qualifier.
  • Invalid subrange fields.
  • att_flags contains an invalid flag.
EPERM One of the following conditions is true:
  • The calling process has neither root authority nor CAP_NUMA_ATTACH privilege.
  • The resource specified by rstype and rsid is not included in the calling process's partition resource set.
ENODEV An invalid rsid SRADID is specified.
ENOTSUP An attempt to get a shared memory region with an SRADID attachment is made and ENHANCED_AFFINITY is disabled.

Examples

The following example attempts to use ra_shmgetv to create a shmat attachable shared memory region, whose first 32 megabytes are distributed using the P_BALANCED policy and the next 48 megabytes using the P_FIRST_TOUCH policy. 

int flags, shm_id;
char *shm_at;
rsethandle_t rsetid;
subrange_t subranges[2] = { 0 };

rsetid = rs_alloc(RS_PARTITION);

subranges[0].su_offset = 0x0000000;
subranges[0].su_length = 0x2000000;
subranges[0].su_rstype = R_RSET;
subranges[0].su_rsid.at_rset = rsetid;
subranges[0].su_policy = P_BALANCED;

subranges[1].su_offset = 0x2000000;
subranges[1].su_length = 0x3000000;
subranges[1].su_rstype = R_RSET;
subranges[1].su_rsid.at_rset = rsetid;
subranges[1].su_policy = P_FIRST_TOUCH;

flags = (IPC_CREAT | SHM_PIN);
shm_id = ra_shmgetv (IPC_PRIVATE, 0x5000000, flags,
	sizeof(subranges) / sizeof(subrange_t), subranges
);
if (shm_id == -1)
{
	perror("ra_shmgetv failed!\n");
	exit(1);
}

Implementation Specifics

The ra_shmget and ra_shmgetv subroutines are part of the Base Operating System (BOS) Runtime.