JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Memory and Thread Placement Optimization Developer's Guide     Oracle Solaris 11.1 Information Library
search filter icon
search icon

Document Information

Preface

1.  Overview of Locality Groups

2.  MPO Observability Tools

3.  Locality Group APIs

Verifying the Interface Version

Initializing the Locality Group Interface

Using lgrp_init()

Using lgrp_fini()

Locality Group Hierarchy

Using lgrp_cookie_stale()

Using lgrp_view()

Using lgrp_nlgrps()

Using lgrp_root()

Using lgrp_parents()

Using lgrp_children()

Locality Group Contents

Using lgrp_resources()

Using lgrp_cpus()

Using lgrp_mem_size()

Locality Group Characteristics

Using lgrp_latency_cookie()

Locality Groups and Thread and Memory Placement

Using lgrp_home()

Using madvise()

Using meminfo()

Locality Group Affinity

Using lgrp_affinity_get()

Using lgrp_affinity_set()

Examples of API Usage

Initializing the Locality Group Interface

Applications must call lgrp_init(3LGRP) in order to use the APIs for traversing the lgroup hierarchy and to discover the contents of the lgroup hierarchy. The call to lgrp_init() gives the application a consistent snapshot of the lgroup hierarchy. The application developer can specify whether the snapshot contains only the resources that are available to the calling thread specifically or the resources that are available to the operating system in general. The lgrp_init() function returns a cookie that is used for the following tasks:

Using lgrp_init()

The lgrp_init() function initializes the lgroup interface and takes a snapshot of the lgroup hierarchy.

#include <sys/lgrp_user.h>
lgrp_cookie_t lgrp_init(lgrp_view_t view);

When the lgrp_init() function is called with LGRP_VIEW_CALLER as the view, the function returns a snapshot that contains only the resources that are available to the calling thread. When the lgrp_init() function is called with LGRP_VIEW_OS as the view, the function returns a snapshot that contains the resources that are available to the operating system. When a thread successfully calls the lgrp_init() function, the function returns a cookie that is used by any function that interacts with the lgroup hierarchy. When a thread no longer needs the cookie, call the lgrp_fini() function with the cookie as the argument.

The lgroup hierarchy consists of a root lgroup that contains all of the machine's CPU and memory resources. The root lgroup might contain other locality groups bounded by smaller latencies.

The lgrp_init() function can return two errors. When a view is invalid, the function returns EINVAL. When there is insufficient memory to allocate the snapshot of the lgroup hierarchy, the function returns ENOMEM.

Using lgrp_fini()

The lgrp_fini(3LGRP) function ends the usage of a given cookie and frees the corresponding lgroup hierarchy snapshot.

#include <sys/lgrp_user.h>
int lgrp_fini(lgrp_cookie_t cookie);

The lgrp_fini() function takes a cookie that represents an lgroup hierarchy snapshot created by a previous call to lgrp_init(). The lgrp_fini() function frees the memory that is allocated to that snapshot. After the call to lgrp_fini(), the cookie is invalid. Do not use that cookie again.

When the cookie passed to the lgrp_fini() function is invalid, lgrp_fini() returns EINVAL.