illumos Memory and Thread Placement Optimization

https://illumos.org/books/lgrps/
Admin
A developer's guide for optimizing computing resources in the illumos operating system through...
Tokens:14,659
Snippets:103
Trust Score:9.5
Update:7 months ago
Show doc for...
Tokens:
Raw
### Set Advice for All ISM Segments (Shell)

Source: https://illumos.org/books/lgrps/lgroups-1.html

This example demonstrates how to apply 'access_lwp' advice to all ISM segments for applications whose exec names start with 'foo'. It involves setting the LD_PRELOAD environment variable and configuring the madvcfg file.

```shell
$ LD_PRELOAD=$LD_PRELOAD:madv.so.1
$ MADVCFGFILE=madvcfg
$ export LD_PRELOAD MADVCFGFILE
$ cat $MADVCFGFILE
        foo*:ism=access_lwp
```

--------------------------------

### Exclude Applications Using Wildcard in madvcfg (Shell)

Source: https://illumos.org/books/lgrps/lgroups-1.html

This example shows an alternative method to exclude applications from advice by using a wildcard '*' in the madvcfg file. This configuration is equivalent to the previous example, setting 'access_many' advice for all applications except 'ls'.

```shell
$ LD_PRELOAD=$LD_PRELOAD:madv.so.1
$ MADVCFGFILE=madvcfg
$ export LD_PRELOAD MADVCFGFILE
$ cat $MADVCFGFILE
        ls:
        *:madv=access_many
```

--------------------------------

### Retrieve memory information with meminfo in C

Source: https://illumos.org/books/lgrps/lgroups-1.html

The meminfo function retrieves specific memory attributes for a set of virtual addresses. The example demonstrates how to allocate memory for results, invoke the function, and parse the validity bitmask to handle errors and extract physical page data.

```C
#include <sys/types.h>
#include <sys/mman.h>

int meminfo(const uint64_t inaddr[], int addr_count,
    const uint_t info_req[], int info_count, uint64_t outdata[],
    uint_t validity[]);

void
print_info(void **addrvec, int how_many)
{
        static const int info[] = {
                MEMINFO_VPHYSICAL,
                MEMINFO_VPAGESIZE};
        uint64_t * inaddr = alloca(sizeof(uint64_t) * how_many);
        uint64_t * outdata = alloca(sizeof(uint64_t) * how_many * 2);
        uint_t * validity = alloca(sizeof(uint_t) * how_many);

        int i;

        for (i = 0; i < how_many; i++)
                inaddr[i] = (uint64_t *)addrvec[i];

        if (meminfo(inaddr, how_many,  info,
                    sizeof (info)/ sizeof(info[0]),
                    outdata, validity) < 0)
                return;

        for (i = 0; i < how_many; i++) {
                if (validity[i] & 1 == 0)
                        printf("address 0x%llx not part of address space\n", inaddr[i]);
                else if (validity[i] & 2 == 0)
                        printf("address 0x%llx has no physical page associated with it\n", inaddr[i]);
                else {
                        char buff[80];
                        if (validity[i] & 4 == 0)
                                strcpy(buff, "<Unknown>");
                        else
                                sprintf(buff, "%lld", outdata[i * 2 + 1]);
                        printf("address 0x%llx is backed by physical page 0x%llx of size %s\n",
                                        inaddr[i], outdata[i * 2], buff);
                }
        }
}
```

--------------------------------

### Walk and Print lgroup Hierarchy

Source: https://illumos.org/books/lgrps/lgroups-1.html

This recursive function traverses the lgroup hierarchy starting from a given lgroup ID. It prints affinity, CPU counts, memory statistics, and parent/child relationships for each node in the hierarchy.

```C
#include <stdio.h>
#include <stdlib.h>
#include <sys/lgrp_user.h>
#include <sys/types.h>

int
lgrp_walk(lgrp_cookie_t cookie, lgrp_id_t lgrp, lgrp_content_t content)
{
	lgrp_affinity_t    aff;
	lgrp_id_t          *children;
	processorid_t      *cpuids;
	int                i;
	int                ncpus;
	int                nchildren;
	int                nparents;
	lgrp_id_t          *parents;
	lgrp_mem_size_t    size;

	printf("LGROUP #%d:\n", lgrp);
	aff = lgrp_affinity_get(P_LWPID, P_MYID, lgrp);
	if (aff == -1) perror ("lgrp_affinity_get");
	printf("\tAFFINITY: %d\n", aff);
	printf("CONTENT %d:\n", content);

	ncpus = lgrp_cpus(cookie, lgrp, NULL, 0, content);
	printf("\t%d CPUS: ", ncpus);
	if (ncpus > 0) {
		cpuids = malloc(ncpus * sizeof (processorid_t));
		ncpus = lgrp_cpus(cookie, lgrp, cpuids, ncpus, content);
		for (i = 0; i < ncpus; i++) printf("%d ", cpuids[i]);
		free(cpuids);
	}
	printf("\n");

	/* Memory and hierarchy traversal logic continues... */
	return (0);
}
```

--------------------------------

### madvise Function Signature and Usage

Source: https://illumos.org/books/lgrps/lgroups-1.html

The `madvise` function advises the kernel on expected memory access patterns for a given virtual memory range. It takes the starting address, length, and an advice flag as parameters. Proper usage can enhance system performance for applications with predictable memory access.

```c
#include <sys/types.h>
#include <sys/mman.h>
int madvise(caddr_t addr, size_t len, int advice);
```

--------------------------------

### Query memory size in an lgroup using lgrp_mem_size

Source: https://illumos.org/books/lgrps/lgroups-1.html

The lgrp_mem_size function returns the amount of installed or free memory in bytes for a specified lgroup. It allows configuration to include memory from the lgroup only or from the lgroup and its descendants.

```C
#include <sys/lgrp_user.h>
lgrp_mem_size_t lgrp_mem_size(lgrp_cookie_t cookie, lgrp_id_t lgrp,
                              int type, int content)
```

--------------------------------

### Get LWP Locality Group Affinity (C)

Source: https://illumos.org/books/lgrps/lgroups-1.html

The `lgrp_affinity_get` function retrieves the locality group affinity for a specified Lightweight Process (LWP). It takes an ID type and ID to identify the LWP, and an lgroup ID. It returns an affinity value or an error code like `EINVAL`, `EPERM`, or `ESRCH`.

```c
#include <sys/lgrp_user.h>
lgrp_affinity_t lgrp_affinity_get(idtype_t idtype, id_t id, lgrp_id_t lgrp);
```

--------------------------------

### lgrp_mem_size

Source: https://illumos.org/books/lgrps/lgroups-1.html

Retrieves the size of installed or free memory in bytes for a given lgroup. It can report memory for the lgroup and its descendants or only for the lgroup directly.

```APIDOC
## lgrp_mem_size

### Description
Retrieves the size of installed or free memory in bytes for a given lgroup. It can report memory for the lgroup and its descendants or only for the lgroup directly.

### Method
N/A (This is a C function, not an HTTP API endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```c
#include <sys/lgrp_user.h>
lgrp_mem_size_t lgrp_mem_size(lgrp_cookie_t cookie, lgrp_id_t lgrp,
                              int type, int content);
```

### Response
#### Success Response
Returns the size of memory (free or installed) in bytes for the specified lgroup.

#### Response Example
```c
// Example return value (memory size in bytes)
lgrp_mem_size_t mem_size = lgrp_mem_size(my_cookie, my_lgrp_id, LGRP_MEM_SZ_FREE, LGRP_CONTENT_ALL);
```

#### Error Codes
- `EINVAL`: Invalid cookie, lgroup ID, or one of the flags.
- `ESRCH`: Specified lgroup ID not found.
```

--------------------------------

### Get Home Lgroup for Process or Thread using lgrp_home (C)

Source: https://illumos.org/books/lgrps/lgroups-1.html

The lgrp_home function determines the 'home' locality group for a given process or thread ID. It returns an lgroup ID and handles various error conditions such as invalid ID types, insufficient permissions, or the target process/thread not being found.

```c
#include <sys/lgrp_user.h>
lgrp_id_t lgrp_home(idtype_t idtype, id_t id);
```

--------------------------------

### GET lgrp_affinity_get

Source: https://illumos.org/books/lgrps/lgroups-1.html

Retrieves the current affinity level of a specified LWP or process for a given locality group.

```APIDOC
## GET lgrp_affinity_get

### Description
Returns the affinity level that a specific LWP or process has for a given locality group.

### Method
GET

### Parameters
#### Path/Argument Parameters
- **idtype** (idtype_t) - Required - The type of ID (P_PID, P_LWPID, P_MYID).
- **id** (id_t) - Required - The ID of the process or LWP.
- **lgrp** (lgrp_id_t) - Required - The ID of the locality group.

### Response
#### Success Response (200)
- **affinity** (lgrp_affinity_t) - The affinity level (LGRP_AFF_STRONG, LGRP_AFF_WEAK, or LGRP_AFF_NONE).

#### Error Handling
- **EINVAL**: Invalid lgroup or ID type.
- **EPERM**: Insufficient permissions.
- **ESRCH**: Lgroup or LWP not found.
```

--------------------------------

### Get Latency Between Lgroups using lgrp_latency_cookie (C)

Source: https://illumos.org/books/lgrps/lgroups-1.html

The lgrp_latency_cookie function retrieves the latency between two locality groups (lgroups). It requires a pre-initialized lgroup cookie and specifies the direction of measurement (e.g., CPU to Memory). The returned value is platform-specific and intended for relative comparison.

```c
#include <sys/lgrp_user.h>
int lgrp_latency_cookie(lgrp_cookie_t cookie, lgrp_id_t from, lgrp_id_t to,
                        lat_between_t between);
```

--------------------------------

### Get root lgroup ID

Source: https://illumos.org/books/lgrps/lgroups-1.html

Retrieves the identifier for the root locality group within the specified hierarchy snapshot.

```C
#include <sys/lgrp_user.h>
lgrp_id_t lgrp_root(lgrp_cookie_t cookie);
```

--------------------------------

### Pattern Matching for Different Advice Types (Shell)

Source: https://illumos.org/books/lgrps/lgroups-1.html

This configuration applies different advice types for various memory regions ('mmap', heap, shared memory) for applications whose exec names begin with 'foo'. It demonstrates pattern matching within the madvcfg file.

```shell
$ LD_PRELOAD=$LD_PRELOAD:madv.so.1
$ MADVCFGFILE=madvcfg
$ export LD_PRELOAD MADVCFGFILE
$ cat $MADVCFGFILE
        foo*:madv=access_many,heap=sequential,shm=access_lwp
```

--------------------------------

### Set Advice for All Applications Except 'ls' (Shell)

Source: https://illumos.org/books/lgrps/lgroups-1.html

This configuration sets 'access_many' advice for all applications except 'ls'. It utilizes the MADV environment variable and the madvcfg file for configuration.

```shell
$ LD_PRELOAD=$LD_PRELOAD:madv.so.1
$ MADV=access_many
$ MADVCFGFILE=madvcfg
$ export LD_PRELOAD MADV MADVCFGFILE
$ cat $MADVCFGFILE
        ls:
```

--------------------------------

### C System Call: meminfo

Source: https://illumos.org/books/lgrps/lgroups-1.html

The meminfo function allows a process to query information about its virtual and physical memory mappings.

```APIDOC
## [SYSTEM_CALL] meminfo

### Description
The meminfo function retrieves information about the virtual and physical memory allocated to the calling process. It supports querying multiple addresses simultaneously for various memory attributes.

### Method
C Function Call

### Endpoint
int meminfo(const uint64_t inaddr[], int addr_count, const uint_t info_req[], int info_count, uint64_t outdata[], uint_t validity[]);

### Parameters
#### Input Parameters
- **inaddr** (uint64_t[]) - Required - Array of virtual addresses to query.
- **addr_count** (int) - Required - Number of addresses in the inaddr array.
- **info_req** (uint_t[]) - Required - Array of request types (e.g., MEMINFO_VPHYSICAL, MEMINFO_VLGRP).
- **info_count** (int) - Required - Number of information types requested per address.

#### Output Parameters
- **outdata** (uint64_t[]) - Required - Array to store the requested information results.
- **validity** (uint_t[]) - Required - Array of bitwise result codes indicating the validity of the input address and requested information.

### Request Example
```c
static const int info[] = { MEMINFO_VPHYSICAL, MEMINFO_VPAGESIZE };
// ... setup arrays ...
meminfo(inaddr, how_many, info, 2, outdata, validity);
```

### Response
#### Success Response (0)
- **outdata** (uint64_t[]) - Array containing the requested memory metadata.
- **validity** (uint_t[]) - Array containing bitwise status flags for each address.

#### Error Handling
- **EFAULT**: Returned if memory arrays cannot be read from or written to.
- **EINVAL**: Returned if info_count is not between 1-31, or addr_count < 0.
```

--------------------------------

### Initialize Locality Group Interface

Source: https://illumos.org/books/lgrps/lgroups-1.html

Initializes the lgroup interface and captures a snapshot of the lgroup hierarchy. The snapshot can be specific to the calling thread or the entire operating system. It returns a cookie used for subsequent lgroup API calls.

```c
#include <sys/lgrp_user.h>

lgrp_cookie_t lgrp_init(lgrp_view_t view);

// Example usage:
lgrp_cookie_t cookie;
cookie = lgrp_init(LGRP_VIEW_CALLER); // Or LGRP_VIEW_OS
```

--------------------------------

### int madvise(caddr_t addr, size_t len, int advice)

Source: https://illumos.org/books/lgrps/lgroups-1.html

The madvise function advises the kernel that a region of user virtual memory is expected to follow a particular pattern of use to optimize resource allocation.

```APIDOC
## [SYSTEM_CALL] madvise

### Description
The `madvise` function advises the kernel that a region of user virtual memory is expected to follow a particular pattern of use. The kernel uses this information to optimize resource management.

### Method
C Function Call

### Endpoint
`int madvise(caddr_t addr, size_t len, int advice);`

### Parameters
#### Path Parameters
- **addr** (caddr_t) - Required - Starting address of the memory range (must be page-aligned).
- **len** (size_t) - Required - Length of the memory range.
- **advice** (int) - Required - The access pattern flag (MADV_ACCESS_DEFAULT, MADV_ACCESS_LWP, MADV_ACCESS_MANY).

### Response
#### Success Response (0)
- **int** - Returns 0 on success.

#### Error Handling
- **EAGAIN** - Mappings are locked for I/O.
- **EINVAL** - Invalid address alignment, length, or advice flag.
- **EIO** - I/O error occurred.
- **ENOMEM** - Address range is invalid or unmapped.
- **ESTALE** - NFS file handle is stale.
```

--------------------------------

### Count system locality groups

Source: https://illumos.org/books/lgrps/lgroups-1.html

Returns the total number of locality groups available in the system for the given snapshot.

```C
#include <sys/lgrp_user.h>
int lgrp_nlgrps(lgrp_cookie_t cookie);
```

--------------------------------

### Verify lgroup Interface Version

Source: https://illumos.org/books/lgrps/lgroups-1.html

Checks if the lgroup interface version is supported by the system. It takes a desired version as input and returns the supported version or LGRP_VER_NONE if unsupported. This is crucial for ensuring API compatibility before use.

```c
#include <sys/lgrp_user.h>

int lgrp_version(const int version);

// Example usage:
if (lgrp_version(LGRP_VER_CURRENT) != LGRP_VER_CURRENT) {
    fprintf(stderr, "Built with unsupported lgroup interface %d\n",
        LGRP_VER_CURRENT);
    exit (1);
}
```

--------------------------------

### Move Memory to a Thread using madvise

Source: https://illumos.org/books/lgrps/lgroups-1.html

This function uses the madvise system call with the MADV_ACCESS_LWP flag to suggest that the kernel move memory in a specified address range closer to the thread accessing it. It requires a virtual address pointer and the length of the memory range.

```C
#include <stdio.h>
#include <sys/mman.h>
#include <sys/types.h>

/*
 * Move memory to thread
 */
void
mem_to_thread(caddr_t addr, size_t len)
{
	if (madvise(addr, len, MADV_ACCESS_LWP) < 0)
		perror("madvise");
}
```

--------------------------------

### Move a Thread to Memory using lgroup Affinity

Source: https://illumos.org/books/lgrps/lgroups-1.html

This function identifies the lgroup associated with a specific virtual address using meminfo and sets a strong thread affinity to that lgroup. It returns 0 on success, or an error code if the memory info or affinity setting fails.

```C
#include <stdio.h>
#include <sys/lgrp_user.h>
#include <sys/mman.h>
#include <sys/types.h>

/*
 * Move a thread to memory
 */
int
thread_to_memory(caddr_t va)
{
	uint64_t    addr;
	ulong_t     count;
	lgrp_id_t   home;
	uint64_t    lgrp;
	uint_t      request;
	uint_t      valid;

	addr = (uint64_t)va;
	count = 1;
	request = MEMINFO_VLGRP;
	if (meminfo(&addr, 1, &request, 1, &lgrp, &valid) != 0) {
		perror("meminfo");
		return (1);
	}

	if (lgrp_affinity_set(P_LWPID, P_MYID, lgrp, LGRP_AFF_STRONG) != 0) {
		perror("lgrp_affinity_set");
		return (2);
	}

	home = lgrp_home(P_LWPID, P_MYID);
	if (home == -1) {
		perror ("lgrp_home");
		return (3);
	}

	if (home != lgrp)
		return (-1);

	return (0);
}
```

--------------------------------

### Find Nearest lgroup with Available Memory in C

Source: https://illumos.org/books/lgrps/lgroups-1.html

This function determines the home lgroup of the current thread and checks for available memory. If the home lgroup is exhausted, it returns the next nearest lgroup.

```C
lgrp_id_t lgrp_nearest(lgrp_cookie_t cookie) {
	lgrp_id_t home;
	longlong_t size;
	home = lgrp_home(P_LWPID, P_MYID);
	size = lgrp_mem_size(cookie, home, LGRP_MEM_SZ_FREE, LGRP_CONTENT_ALL);
	if (size == -1) perror("lgrp_mem_size");
	if (size > 0) return (home);
	return (lgrp_next_nearest(cookie, home));
}
```

--------------------------------

### Retrieve CPU IDs in an lgroup using lgrp_cpus

Source: https://illumos.org/books/lgrps/lgroups-1.html

The lgrp_cpus function returns the number of CPUs in a given lgroup and can optionally populate an array with CPU IDs. It supports filtering by direct membership or including descendants.

```C
#include <sys/lgrp_user.h>
int lgrp_cpus(lgrp_cookie_t cookie, lgrp_id_t lgrp, processorid_t *cpuids,
              uint_t count, int content);
```

--------------------------------

### Find Closest Parent lgroup with Memory in C

Source: https://illumos.org/books/lgrps/lgroups-1.html

This function retrieves the parent lgroups of a given lgroup and iterates through them to find the one with the lowest latency and available memory. It handles cases where a parent lacks memory by querying the next nearest ancestor.

```C
int nparents;
lgrp_id_t *parents;
lgrp_mem_size_t size;

nparents = lgrp_parents(cookie, from, NULL, 0);
if (nparents == -1) {
	perror("lgrp_parents");
	return (LGRP_NONE);
}
if (nparents == 0) {
	return (from);
}
parents = malloc(nparents * sizeof (lgrp_id_t));
nparents = lgrp_parents(cookie, from, parents, nparents);
if (nparents == -1) {
	perror("lgrp_parents");
	free(parents);
	return (LGRP_NONE);
}
closest = LGRP_NONE;
lowest = INT_MAX;
for (i = 0; i < nparents; i++) {
	lgrp_id_t lgrp;
	size = lgrp_mem_size(cookie, parents[i], LGRP_MEM_SZ_FREE, LGRP_CONTENT_ALL);
	if (size > 0)
		lgrp = parents[i];
	else {
		if (size == -1) perror("lgrp_mem_size");
		lgrp = lgrp_next_nearest(cookie, parents[i]);
		if (lgrp == LGRP_NONE) continue;
	}
	latency = lgrp_latency_cookie(lgrp, lgrp);
	if (latency == -1) {
		perror("lgrp_latency_cookie");
		continue;
	}
	if (latency < lowest) {
		closest = lgrp;
		lowest = latency;
	}
}
free(parents);
return (closest);
```

--------------------------------

### Retrieve child lgroups

Source: https://illumos.org/books/lgrps/lgroups-1.html

Returns the number of child lgroups for a specified lgroup and optionally populates an array with their IDs.

```C
#include <sys/lgrp_user.h>
int lgrp_children(lgrp_cookie_t cookie, lgrp_id_t parent,
                  lgrp_id_t *lgrp_array, uint_t lgrp_array_size);
```

--------------------------------

### lgrp_cpus

Source: https://illumos.org/books/lgrps/lgroups-1.html

Retrieves the number of CPUs in a given lgroup and optionally fills an array with their IDs. It supports fetching CPUs from the lgroup and its descendants or only from the lgroup directly.

```APIDOC
## lgrp_cpus

### Description
Retrieves the number of CPUs in a given lgroup and optionally fills an array with their IDs. It supports fetching CPUs from the lgroup and its descendants or only from the lgroup directly.

### Method
N/A (This is a C function, not an HTTP API endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```c
#include <sys/lgrp_user.h>
int lgrp_cpus(lgrp_cookie_t cookie, lgrp_id_t lgrp, processorid_t *cpuids,
              uint_t count, int content);
```

### Response
#### Success Response
Returns the number of CPUs in the specified lgroup. If `cpuids` is not NULL and `count` is not zero, it populates `cpuids` with processor IDs.

#### Response Example
```c
// Example return value (number of CPUs)
int cpu_count = lgrp_cpus(my_cookie, my_lgrp_id, NULL, 0, LGRP_CONTENT_DIRECT);
```

#### Error Codes
- `EINVAL`: Invalid cookie, lgroup ID, or one of the flags.
- `ESRCH`: Specified lgroup ID not found.
```

--------------------------------

### Retrieve parent lgroups

Source: https://illumos.org/books/lgrps/lgroups-1.html

Returns the number of parent lgroups for a specified lgroup and optionally populates an array with their IDs.

```C
#include <sys/lgrp_user.h>
int lgrp_parents(lgrp_cookie_t cookie, lgrp_id_t child,
                 lgrp_id_t *lgrp_array, uint_t lgrp_array_size);
```

--------------------------------

### lgrp_latency_cookie

Source: https://illumos.org/books/lgrps/lgroups-1.html

Retrieves the latency between hardware resources in different locality groups (lgroups). It takes a cookie representing an lgroup hierarchy snapshot and IDs of the source and target lgroups, along with a type specifying the nature of the latency to measure (e.g., CPU to Memory).

```APIDOC
## lgrp_latency_cookie

### Description
Calculates and returns the latency between a CPU in one lgroup and the memory in another lgroup, or within the same lgroup if both source and target are identical. The returned value is a platform-specific, relative measure for comparison within a domain.

### Method
N/A (This is a C function, not an HTTP endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```c
#include <sys/lgrp_user.h>
int lgrp_latency_cookie(lgrp_cookie_t cookie, lgrp_id_t from, lgrp_id_t to,
                        lat_between_t between);
```

### Response
#### Success Response (Latency Value)
- **int** - A value representing the latency between the specified lgroups.

#### Response Example
```c
// Example of a successful return value (actual value is platform-specific)
int latency = lgrp_latency_cookie(my_cookie, cpu_lgroup_id, mem_lgroup_id, LGRP_LAT_CPU_TO_MEM);
```

#### Error Codes
- **EINVAL**: If the provided lgroup ID is invalid.
- **ESRCH**: If the specified lgroup ID is not found, the 'from' lgroup has no CPUs, or the 'to' lgroup has no memory.
```

--------------------------------

### Retrieve lgroup resource counts using lgrp_resources

Source: https://illumos.org/books/lgrps/lgroups-1.html

The lgrp_resources function returns the number of CPU or memory resources within a specified lgroup. It requires a valid lgroup cookie and supports populating an array with lgroup IDs if provided.

```C
#include <sys/lgrp_user.h>
int lgrp_resources(lgrp_cookie_t cookie, lgrp_id_t lgrp, lgrp_id_t *lgrpids,
                   uint_t count, lgrp_rsrc_t type);
```

--------------------------------

### Check lgrp cookie staleness

Source: https://illumos.org/books/lgrps/lgroups-1.html

Determines if the provided lgroup hierarchy snapshot cookie is current. If stale, the cookie must be refreshed using lgrp_fini and lgrp_init.

```C
#include <sys/lgrp_user.h>
int lgrp_cookie_stale(lgrp_cookie_t cookie);
```

--------------------------------

### lgrp_home

Source: https://illumos.org/books/lgrps/lgroups-1.html

Determines the home locality group (lgroup) for a given process or thread. It requires specifying the type of ID (process or thread) and the corresponding ID value.

```APIDOC
## lgrp_home

### Description
Returns the home lgroup ID for a specified process or thread. This function is used to discover the default placement of threads and their associated memory.

### Method
N/A (This is a C function, not an HTTP endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```c
#include <sys/lgrp_user.h>
lgrp_id_t lgrp_home(idtype_t idtype, id_t id);
```

### Response
#### Success Response (lgrp_id_t)
- **lgrp_id_t** - The ID of the home locality group for the specified process or thread.

#### Response Example
```c
// Example of a successful return value
lgrp_id_t home_lgroup = lgrp_home(P_MYID, 0); // Get home lgroup for current thread
```

#### Error Codes
- **EINVAL**: If the provided `idtype` is invalid.
- **EPERM**: If the effective user is not superuser and does not match the real or effective user ID of the target thread.
- **ESRCH**: If the specified process or thread ID is not found.
```

--------------------------------

### Set LWP Locality Group Affinity (C)

Source: https://illumos.org/books/lgrps/lgroups-1.html

The `lgrp_affinity_set` function sets the locality group affinity for a specified LWP or set of LWPs. It takes an ID type, ID, lgroup ID, and the desired affinity level. It returns 0 on success or an error code like `EINVAL`, `EPERM`, or `ESRCH`.

```c
#include <sys/lgrp_user.h>
int lgrp_affinity_set(idtype_t idtype, id_t id, lgrp_id_t lgrp,
                      lgrp_affinity_t affinity);
```

--------------------------------

### Retrieve lgrp snapshot view

Source: https://illumos.org/books/lgrps/lgroups-1.html

Returns the view type (LGRP_VIEW_OS or LGRP_VIEW_CALLER) associated with the given lgroup hierarchy snapshot cookie.

```C
#include <sys/lgrp_user.h>
lgrp_view_t lgrp_view(lgrp_cookie_t cookie);
```

--------------------------------

### lgrp_resources

Source: https://illumos.org/books/lgrps/lgroups-1.html

Retrieves the number of CPU or memory resources within a specified lgroup. It can optionally populate an array with the IDs of lgroups that directly contain these resources.

```APIDOC
## lgrp_resources

### Description
Retrieves the number of CPU or memory resources contained in a specified lgroup. It can optionally populate an array with the IDs of lgroups that directly contain these resources.

### Method
N/A (This is a C function, not an HTTP API endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```c
#include <sys/lgrp_user.h>
int lgrp_resources(lgrp_cookie_t cookie, lgrp_id_t lgrp, lgrp_id_t *lgrpids,
                   uint_t count, lgrp_rsrc_t type);
```

### Response
#### Success Response
Returns the number of resources (CPU or memory) in the specified lgroup. If `lgrpids` is not NULL and `count` is not zero, it populates `lgrpids` with lgroup IDs.

#### Response Example
```c
// Example return value (number of resources)
int resource_count = lgrp_resources(my_cookie, my_lgrp_id, NULL, 0, LGRP_RSRC_CPU);
```

#### Error Codes
- `EINVAL`: Invalid cookie, lgroup ID, or type.
- `ESRCH`: Specified lgroup ID not found.
```

--------------------------------

### POST lgrp_affinity_set

Source: https://illumos.org/books/lgrps/lgroups-1.html

Sets the affinity level for a specified LWP or process for a given locality group.

```APIDOC
## POST lgrp_affinity_set

### Description
Sets the affinity level for a LWP or set of LWPs for a given locality group.

### Method
POST

### Parameters
#### Request Body
- **idtype** (idtype_t) - Required - The type of ID (P_PID, P_LWPID, P_MYID).
- **id** (id_t) - Required - The ID of the process or LWP.
- **lgrp** (lgrp_id_t) - Required - The ID of the locality group.
- **affinity** (lgrp_affinity_t) - Required - The desired affinity level (LGRP_AFF_STRONG, LGRP_AFF_WEAK, LGRP_AFF_NONE).

### Response
#### Success Response (0)
- **status** (int) - Returns 0 on success.

#### Error Handling
- **EINVAL**: Invalid lgroup, affinity, or ID type.
- **EPERM**: Insufficient permissions.
- **ESRCH**: Lgroup or LWP not found.
```

--------------------------------

### Finalize Locality Group Interface

Source: https://illumos.org/books/lgrps/lgroups-1.html

Frees the lgroup hierarchy snapshot associated with a given cookie. This function should be called when the lgroup interface is no longer needed to release allocated resources. Using an invalid cookie will result in an error.

```c
#include <sys/lgrp_user.h>

int lgrp_fini(lgrp_cookie_t cookie);

// Example usage:
if (lgrp_fini(cookie) != 0) {
    // Handle error, e.g., invalid cookie
}
```
Tokens:
Raw