This chapter describes resource controls and their properties.Overview of Resource Controls Resource Controls Flags and Actions Resource Controls API Functions Resource Control Code Examples Programming Issues Associated With Resource Controls Use the extended accounting facility to determine the resource consumption of workloads on your system. After the resource consumption has been determined, use the resource control facility to place bounds on resource usage. Bounds that are placed on resources prevent workloads from over-consuming resources.For an overview of resource controls and example commands for administering resource controls, see Chapter 6, Resource Controls (Overview), in System Administration Guide: Solaris Containers-Resource Management and Solaris Zones and Chapter 7, Administering Resource Controls (Tasks), in System Administration Guide: Solaris Containers-Resource Management and Solaris Zones.The resource control facility adds the following benefits.Dynamically setResource controls can be adjusted while the system is running. Containment level granularityResource controls are arranged in a containment level of zone, project, task, or process. The containment level simplifies the configuration and aligns the collected values closer to the particular zone, project, task, or process. This section describes flags, actions, and signals associated with resource controls.rlimit is process-based. rlimit establishes a restricting boundary on the consumption of a variety of system resources by a process. Each process that the process creates inherits from the original process. A resource limit is defined by a pair of values. The values specify the current (soft) limit and the maximum (hard) limit. A process might irreversibly lower its hard limit to any value that is greater than or equal to the soft limit. Only a process with superuser ID can raise the hard limit. See setrlimit and getrlimit.The rlimit structure contains two members that define the soft limit and hard limit.rlim_t rlim_cur; /* current (soft) limit */ rlim_t rlim_max /* hard limit */ rctl extends the process-based limits of rlimit by controlling resource consumption by processes, tasks, and projects defined in the project database.The rctl mechanism is preferred to the use of rlimit to set resource limits. The only reason to use the rlimit facility is when portability is required across UNIX platforms. Applications fall into the following broad categories depending on how an application deals with resource controls. Based on the action that is taken, resource controls can be further classified. Most report an error and terminate operation. Other resource controls allow applications to resume operation and adapt to the reduced resource usage. A progressive chain of actions at increasing values can be specified for each resource control.The list of attributes for a resource control consists of a privilege level, a threshold value, and an action that is taken when the threshold is exceeded. Each threshold value on a resource control must be associated with one of the following privilege levels:RCPRIV_BASICPrivilege level can be modified by the owner of the calling process. RCPRIV_BASIC is associated with a resource's soft limit. RCPRIV_PRIVILEGEDPrivilege level can be modified only by privileged (superuser) callers. RCPRIV_PRIVILEGED is associated with a resource's hard limit. RCPRIV_SYSTEMPrivilege level remains fixed for the duration of the operating system instance. Figure 5–2 shows the timeline for setting privilege levels for signals that are defined by the /etc/project file process.max-cpu-time resource control. The local action and local flags are applied to the current resource control value represented by this resource control block. Local actions and local flags are value-specific. For each threshold value that is placed on a resource control, the following local actions and local flags are available:RCTL_LOCAL_NOACTIONNo local action is taken when this resource control value is exceeded. RCTL_LOCAL_SIGNALThe specified signal, set by rctlblk_set_local_action, is sent to the process that placed this resource control value in the value sequence. RCTL_LOCAL_DENYWhen this resource control value is encountered, the request for the resource is denied. Set on all values if RCTL_GLOBAL_DENY_ALWAYS is set for this control. Cleared on all values if RCTL_GLOBAL_DENY_NEVER is set for this control. RCTL_LOCAL_MAXIMALThis resource control value represents a request for the maximum amount of resource for this control. If RCTL_GLOBAL_INFINITE is set for this resource control, RCTL_LOCAL_MAXIMAL indicates an unlimited resource control value that is never exceeded. Global flags apply to all current resource control values represented by this resource control block. Global actions and global flags are set by rctladm(1M). Global actions and global flags cannot be set with setrctl. Global flags apply to all resource controls. For each threshold value that is placed on a resource control, the following global actions and global flags are available:RCTL_GLOBAL_NOACTIONNo global action is taken when a resource control value is exceeded on this control. RCTL_GLOBAL_SYSLOGA standard message is logged by the syslog facility when any resource control value on a sequence associated with this control is exceeded. RCTL_GLOBAL_SECONDSDefines the unit string of the limit value as seconds. RCTL_GLOBAL_COUNTDefines the unit string of the limit value as count. RCTL_GLOBAL_BYTESDefines the unit string of the limit value as bytes. RCTL_GLOBAL_SYSLOG_NEVERFlag means that RCTL_GLOBAL_SYSLOG cannot be set for this resource control through rctladm1M. RCTL_GLOBAL_NOBASICNo values with the RCPRIV_BASIC privilege are permitted on this control. RCTL_GLOBAL_LOWERABLENon-privileged callers are able to lower the value of privileged resource control values on this control. RCTL_GLOBAL_DENY_ALWAYSThe action that is taken when a control value is exceeded on this control always includes denial of the resource. RCTL_GLOBAL_DENY_NEVERThe action that is taken when a control value is exceeded on this control always excludes denial of the resource. The resource is always granted, although other actions can also be taken. RCTL_GLOBAL_FILE_SIZEThe valid signals for local actions include the SIGXFSZ signal. RCTL_GLOBAL_CPU_TIMEThe valid signals for local actions include the SIGXCPU signal. RCTL_GLOBAL_SIGNAL_NEVERNo local actions are permitted on this control. The resource is always granted. RCTL_GLOBAL_INFINITEThis resource control supports the concept of an unlimited value. Generally, an unlimited value applies only to accumulation-oriented resources, such as CPU time. RCTL_GLOBAL_UNOBSERVABLEGenerally, a task or project related resource control does not support observational control values. An RCPRIV_BASIC privileged control value placed on a task or process generates an action only if the value is exceeded by the process that placed the value. The following figure shows the resource control sets associated with tasks, processes and a project.

represents resource control sets for a task, project, and processes.

More than one resource control can exist on a resource, each resource control at a containment level in the process model. Resource controls can be active on the same resource for both a process and collective task or collective project. In this case, the action for the process takes precedence. For example, action is taken on process.max-cpu-time before task.max-cpu-time if both controls are encountered simultaneously.Resource controls associated with a project include the following:project.cpu-capAbsolute limit on the amount of CPU resources that can be consumed by a project. A value of 100 means 100 percent of one CPU as the project.cpu-cap setting. A value of 125 is 125 percent, because 100 percent corresponds to one full CPU on the system when using CPU caps. project.cpu-sharesThe number of CPU shares that are granted to this project for use with the fair share scheduler, FSS(7). project.max-crypto-memoryTotal amount of kernel memory that can be used by libpkcs11 for hardware crypto acceleration. Allocations for kernel buffers and session-related structures are charged against this resource control. project.max-locked-memoryTotal amount of physical locked memory allowed.Note that this resource control replaced project.max-device-locked-memory, which has been removed. project.max-msg-idsMaximum number of System V message queues allowed for a project. project.max-port-idsMaximum allowable number of event ports. project.max-sem-idsMaximum number of semaphore IDs allowed for a project. project.max-shm-idsMaximum number of shared memory IDs allowed for this project. project.max-msg-idsMaximum number of message queue IDs allowed for this project. project.max-shm-memoryTotal amount of System V shared memory allowed for this project. project.max-lwpsMaximum number of LWPs simultaneously available to this project. project.max-tasksMaximum number of tasks allowable in this project. project.max-contractsMaximum number of contracts allowed in this project. Resource controls associated with tasks include the following:task.max-cpu-timeMaximum CPU time (seconds) available to this task's processes. task.max-lwpsMaximum number of LWPs simultaneously available to this task's processes. Resource controls associated with processes include the following:process.max-address-spaceMaximum amount of address space (bytes), as summed over segment sizes, available to this process. process.max-core-sizeMaximum size (bytes) of a core file that is created by this process. process.max-cpu-timeMaximum CPU time (seconds) available to this process. process.max-file-descriptorMaximum file descriptor index that is available to this process. process.max-file-sizeMaximum file offset (bytes) available for writing by this process. process.max-msg-messagesMaximum number of messages on a message queue. This value is copied from the resource control at msgget time. process.max-msg-qbytesMaximum number (bytes) of messages on a message queue. This value is copied from the resource control at msgget time.When you set a new project.max-msg-qbytes value, initialization occurs only on the subsequently created values. The new project.max-msg-qbytes value does not effect existing values. process.max-sem-nsemsMaximum number of semaphores allowed for a semaphore set. process.max-sem-opsMaximum number of semaphore operations that are allowed for a semop call. This value is copied from the resource control at msgget time.A new project.max-sem-ops value only affects the initialization of subsequently created values and has no effect on existing values. process.max-port-eventsMaximum number of events that are allowed per event port. Zone-wide resource controls are available on a system with zones installed. Zone-wide resource controls limit the total resource usage of all process entities within a zone.zone.cpu-capAbsolute limit on the amount of CPU resources that can be consumed by a non-global zone. A value of 100 means 100 percent of one CPU as the project.cpu-cap setting. A value of 125 is 125 percent, because 100 percent corresponds to one full CPU on the system when using CPU caps. zone.cpu-sharesLimit on the number of fair share scheduler (FSS) CPU shares for a zone. The scheduling class must be FSS. CPU shares are first allocated to the zone, and then further subdivided among projects within the zone as specified in the project.cpu-shares entries. A zone with a higher number of zone.cpu-shares is allowed to use more CPU than a zone with a low number of shares. zone.max-locked-memoryTotal amount of physical locked memory available to a zone. zone.max-lwpsMaximum number of LWPs simultaneously available to this zone zone.max-msg-idsMaximum number of message queue IDs allowed for this zone zone.max-sem-idsMaximum number of semaphore IDs allowed for this zone zone.max-shm-idsMaximum number of shared memory IDs allowed for this zone zone.max-shm-memoryTotal amount of shared memory allowed for this zone zone.max-swapTotal amount of swap that can be consumed by user process address space mappings and tmpfs mounts for this zone. For information on configuring zone-wide resource controls, see Chapter 17, Non-Global Zone Configuration (Overview), in System Administration Guide: Solaris Containers-Resource Management and Solaris Zones and Chapter 18, Planning and Configuring Non-Global Zones (Tasks), in System Administration Guide: Solaris Containers-Resource Management and Solaris Zones. Note that it is possible to use the zonecfg command to apply a zone-wide resource control to the global zone on a system with non-global zones installed. For each threshold value that is placed on a resource control, the following restricted set of signals is available:SIGBARTTerminate the process. SIGXRESSignal generated by resource control facility when the resource control limit is exceeded. SIGHUPWhen carrier drops on an open line, the process group that controls the terminal is sent a hangup signal, SIGHUP. SIGSTOPJob control signal. Stop the process. Stop signal not from terminal. SIGTERMTerminate the process. Termination signal sent by software. SIGKILLTerminate the process. Kill the program. SIGXFSXTerminate the process. File size limit exceeded. Available only to resource controls with the RCTL_GLOBAL_FILE_SIZE property. SIGXCPUTerminate the process. CPU time limit exceeded. Available only to resource controls with the RCTL_GLOBAL_CPUTIME property. Other signals might be permitted due to global properties of a specific control.Calls to setrctl with illegal signals fail.

setting privilege levels for signals

The resource controls API contains functions that: Operate on Action-Value Pairs of a Resource Control Operate on Local Modifiable Values Retrieve Local Read-Only Values Retrieve Global Read-Only Actions The following list contains the functions that set or get the resource control block.setrctl2 getrctl2 The following list contains the functions associated with the local, modifiable resource control block.rctlblk_set_privilege3C rctlblk_get_privilege3C rctlblk_set_value3C rctlblk_get_value3C rctlblk_set_local_action3C rctlblk_get_local_action3C rctlblk_set_local_flags3C rctlblk_get_local_flags3C The following list contains the functions associated with the local, read-only resource control block.rctlblk_get_recipient_pid3C rctlblk_get_firing_time3C rctlblk_get_enforced_value3C The following list contains the functions associated with the global, read-only resource control block.rctlblk_get_global_action3C rctlblk_get_global_flags3C The following example is the master observer process. Figure 5–3 shows the resource controls for the master observing process.The line break is not valid in an /etc/project file. The line break is shown here only to allow the example to display on a printed or displayed page. Each entry in the /etc/project file must be on a separate line.

diagram showing resource controls for the master observing process

The key points for the example include the following:Because the task's limit is privileged, the application cannot change the limit, or specify an action, such as a signal. A master process solves this problem by establishing the same resource control as a basic resource control on the task. The master process uses the same value or a little less on the resource, but with a different action, signal = XRES. The master process creates a thread to wait for this signal. The rctlblk is opaque. The struct needs to be dynamically allocated. Note the blocking of all signals before creating the thread, as required by sigwait(2). The thread calls sigwait(2) to block for the signal. If sigwait returns the SIGXRES signal, the thread notifies the master process' children, which adapts to reduce the number of LWPs being used. Each child should also be modelled similarly, with a thread in each child, waiting for this signal, and adapting its process' LWP usage appropriately. rctlblk_t *mlwprcb; sigset_t smask; /* Omit return value checking/error processing to keep code sample short */ /* First, install a RCPRIV_BASIC, v=1000, signal=SIGXRES rctl */ mlwprcb = calloc(1, rctlblk_size()); /* rctl blocks are opaque: */ rctlblk_set_value(mlwprcb, 1000); rctlblk_set_privilege(mlwprcb, RCPRIV_BASIC); rctlblk_set_local_action(mlwprcb, RCTL_LOCAL_SIGNAL, SIGXRES); if (setrctl("task.max-lwps", NULL, mlwprcb, RCTL_INSERT) == -1) { perror("setrctl"); exit (1); } /* Now, create the thread which waits for the signal */ sigemptyset(&smask); sigaddset(&smask, SIGXRES); thr_sigsetmask(SIG_BLOCK, &smask, NULL); thr_create(NULL, 0, sigthread, (void *)SIGXRES, THR_DETACHED, NULL)); /* Omit return value checking/error processing to keep code sample short */ void *sigthread(void *a) { int sig = (int)a; int rsig; sigset_t sset; sigemptyset(&sset); sigaddset(&sset, sig); while (1) { rsig = sigwait(&sset); if (rsig == SIGXRES) { notify_all_children(); /* e.g. sigsend(P_PID, child_pid, SIGXRES); */ } } } The following example lists all the value-action pairs for a specific resource control, task.max-lwps. The key point for the example is that getrctl(2) takes two resource control blocks, and returns the resource control block for the RCTL_NEXT flag. To iterate through all resource control blocks, repeatedly swap the resource control block values, as shown here using the rcb_tmp rctl block.rctlblk_t *rcb1, *rcb2, *rcb_tmp; ... /* Omit return value checking/error processing to keep code sample short */ rcb1 = calloc(1, rctlblk_size()); /* rctl blocks are opaque: */ /* "rctlblk_t rcb" does not work */ rcb2 = calloc(1, rctlblk_size()); getrctl("task.max-lwps", NULL, rcb1, RCTL_FIRST); while (1) { print_rctl(rcb1); rcb_tmp = rcb2; rcb2 = rcb1; rcb1 = rcb_tmp; /* swap rcb1 with rcb2 */ if (getrctl("task.max-lwps", rcb2, rcb1, RCTL_NEXT) == -1) { if (errno == ENOENT) { break; } else { perror("getrctl"); exit (1); } } } The key points of the example include the following:This example is similar to the example shown in Set pool.comment Property and Add New Property. Use bcopy, rather than buffer swapping as in List all the Value-Action Pairs for a Specific Resource Control. To change the resource control value, call setrctl with the RCTL_REPLACE flag. The new resource control block is identical to the old resource control block except for the new control value.rctlblk_set_value(blk1, nshares); if (setrctl("project.cpu-shares", blk2, blk1, RCTL_REPLACE) != 0) The example gets the project's CPU share allocation, project.cpu-shares, and changes its value to nshares./* Omit return value checking/error processing to keep code sample short */ blk1 = malloc(rctlblk_size()); getrctl("project.cpu-shares", NULL, blk1, RCTL_FIRST); my_shares = rctlblk_get_value(blk1); printout_my_shares(my_shares); /* if privileged, do the following to */ /* change project.cpu-shares to "nshares" */ blk1 = malloc(rctlblk_size()); blk2 = malloc(rctlblk_size()); if (getrctl("project.cpu-shares", NULL, blk1, RCTL_FIRST) != 0) { perror("getrctl failed"); exit(1); } bcopy(blk1, blk2, rctlblk_size()); rctlblk_set_value(blk1, nshares); if (setrctl("project.cpu-shares", blk2, blk1, RCTL_REPLACE) != 0) { perror("setrctl failed"); exit(1); } In the following example, an application has set a privileged limit of 3000 LWPs that may not be exceeded. In addition, the application has set a basic limit of 2000 LWPs. When this limit is exceeded, a SIGXRES is sent to the application. Upon receiving a SIGXRES, the application might send notification to its child processes that might in turn reduce the number of LWPs the processes use or need. /* Omit return value and error checking */ #include <rctl.h> rctlblk_t *rcb1, *rcb2; /* * Resource control blocks are opaque * and must be explicitly allocated. */ rcb1 = calloc(rctlblk_size()); rcb2 = calloc(rctlblk_size()); /* Install an RCPRIV_PRIVILEGED, v=3000: do not allow more than 3000 LWPs */ rctlblk_set_value(rcb1, 3000); rctlblk_set_privilege(rcb1, RCPRIV_PRIVILEGED); rctlblk_set_local_action(rcb1, RCTL_LOCAL_DENY); setrctl("task.max-lwps", NULL, rcb1, RCTL_INSERT); /* Install an RCPRIV_BASIC, v=2000 to send SIGXRES when LWPs exceeds 2000 */ rctlblk_set_value(rcb2, 2000); rctlblk_set_privilege(rcb2, RCPRIV_BASIC); rctlblk_set_local_action(rcb2, RCTL_LOCAL_SIGNAL, SIGXRES); setrctl("task.max-lwps", NULL, rcb2, RCTL_INSERT); Consider the following issues when writing your application:The resource control block is opaque. The control block needs to be dynamically allocated. If a basic resource control is established on a task or project, the process that establishes this resource control becomes an observer. The action for this resource control block is applied to the observer. However, some resources cannot be observed in this manner. If a privileged resource control is set on a task or project, no observer process exists. However, any process that violates the limit becomes the subject of the resource control action. Only one action is permitted for each type: global and local. Only one basic rctl is allowed per process per resource control.