Applications must call the lgrp_init() function to use the APIs for traversing the lgroup hierarchy and to discover the contents of the lgroup hierarchy. Call to the lgrp_init() function gives the application a consistent snapshot of the lgroup hierarchy. The application developer can specify whether the snapshot must contain only the resources that are available to the calling thread or the resources that are available to the operating system.
The lgrp_init() function returns a cookie that is used for the following tasks:
Traversing the lgroup hierarchy
Determining the contents of an lgroup
Determining whether the snapshot is current
For more information, see the lgrp_init(3LGRP) man page.
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 with the resources available only to the calling thread. When the lgrp_init() function is called with LGRP_VIEW_OS as the view, the function returns a snapshot with the resources 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 interacting with the lgroup hierarchy. When a thread no longer needs the lgroup hierarchy, call the lgrp_fini() function with the cookie as the argument.
The lgroup hierarchy consists of a root lgroup that contains all of the system'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.
The lgrp_fini() function invalidates the given cookie 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 and cannot be used again.
When the cookie passed to the lgrp_fini() function is invalid, lgrp_fini() returns EINVAL. For more information about lgrp_fini() function, see the lgrp_fini(3LGRP) man page.