1.\" Copyright (c) 2001, Sun Microsystems, Inc. All Rights Reserved 2.\" Copyright 2019 Joyent, Inc. 3.\" 4.\" The contents of this file are subject to the terms of the 5.\" Common Development and Distribution License (the "License"). 6.\" You may not use this file except in compliance with the License. 7.\" 8.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 9.\" or http://www.opensolaris.org/os/licensing. 10.\" See the License for the specific language governing permissions 11.\" and limitations under the License. 12.\" 13.\" When distributing Covered Code, include this CDDL HEADER in each 14.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 15.\" If applicable, add the following below this CDDL HEADER, with the 16.\" fields enclosed by brackets "[]" replaced with your own identifying 17.\" information: Portions Copyright [yyyy] [name of copyright owner] 18.\" 19.Dd December 17, 2019 20.Dt FSS 4 21.Os 22.Sh NAME 23.Nm FSS 24.Nd Fair share scheduler 25.Sh DESCRIPTION 26The fair share scheduler (FSS) guarantees application performance by explicitly 27allocating shares of CPU resources to projects. 28A share indicates a project's 29entitlement to available CPU resources. 30Because shares are meaningful only in 31comparison with other project's shares, the absolute quantity of shares is not 32important. 33Any number that is in proportion with the desired CPU entitlement 34can be used. 35.Pp 36The goals of the FSS scheduler differ from the traditional time-sharing 37scheduling class (TS). 38In addition to scheduling individual LWPs, the FSS 39scheduler schedules projects against each other, making it impossible for any 40project to acquire more CPU cycles simply by running more processes 41concurrently. 42.Pp 43A project's entitlement is individually calculated by FSS independently for 44each processor set if the project contains processes bound to them. 45If a 46project is running on more than one processor set, it can have different 47entitlements on every set. 48A project's entitlement is defined as a ratio 49between the number of shares given to a project and the sum of shares of all 50active projects running on the same processor set. 51An active project is one 52that has at least one running or runnable process. 53Entitlements are recomputed 54whenever any project becomes active or inactive, or whenever the number of 55shares is changed. 56.Pp 57Processor sets represent virtual machines in the FSS scheduling class and 58processes are scheduled independently in each processor set. 59That is, processes 60compete with each other only if they are running on the same processor set. 61When a processor set is destroyed, all processes that were bound to it are 62moved to the default processor set, which always exists. 63Empty processor sets 64(that is, sets without processors in them) have no impact on the FSS scheduler 65behavior. 66.Pp 67If a processor set contains a mix of TS/IA and FSS processes, the fairness of 68the FSS scheduling class can be compromised because these classes use the same 69range of priorities. 70Fairness is most significantly affected if processes 71running in the TS scheduling class are CPU-intensive and are bound to 72processors within the processor set. 73As a result, you should avoid having 74processes from TS/IA and FSS classes share the same processor set. 75RT and FSS 76processes use disjoint priority ranges and therefore can share processor sets. 77.Pp 78As projects execute, their CPU usage is accumulated over time. 79The FSS 80scheduler periodically decays CPU usages of every project by multiplying it 81with a decay factor, ensuring that more recent CPU usage has greater weight 82when taken into account for scheduling. 83The FSS scheduler continually adjusts 84priorities of all processes to make each project's relative CPU usage converge 85with its entitlement. 86.Pp 87While FSS is designed to fairly allocate cycles over a long-term time period, 88it is possible that projects will not receive their allocated shares worth of 89CPU cycles due to uneven demand. 90This makes one-shot, instantaneous analysis of 91FSS performance data unreliable. 92.Pp 93Note that share is not the same as utilization. 94A project may be allocated 50% 95of the system, although on the average, it uses just 20%. 96Shares serve to cap a 97project's CPU usage only when there is competition from other projects running 98on the same processor set. 99When there is no competition, utilization may be 100larger than entitlement based on shares. 101Allocating a small share to a busy 102project slows it down but does not prevent it from completing its work if the 103system is not saturated. 104.Pp 105The configuration of CPU shares is managed by the name server as a property of 106the 107.Xr project 5 108database. 109In the following example, an entry in the 110.Pa /etc/project 111file sets the number of shares for project 112.Sy x-files 113to 10: 114.Bd -literal -offset 2n 115x-files:100::::project.cpu-shares=(privileged,10,none) 116.Ed 117.Pp 118Projects with undefined number of shares are given one share each. 119This means 120that such projects are treated with equal importance. 121Projects with 0 shares 122only run when there are no projects with non-zero shares competing for the same 123processor set. 124The maximum number of shares that can be assigned to one project 125is 65535. 126.Pp 127You can use the 128.Xr prctl 1 129command to determine the current share 130assignment for a given project: 131.Bd -literal -offset 2n 132$ prctl -n project.cpu-shares -i project x-files 133.Ed 134.Pp 135or to change the amount of shares if you have root privileges: 136.Bd -literal -offset 2n 137# prctl -r -n project.cpu-shares -v 5 -i project x-files 138.Ed 139.Pp 140See the 141.Xr prctl 1 142man page for additional information on how to modify and 143examine resource controls associated with active processes, tasks, or projects 144on the system. 145See 146.Xr resource_controls 7 147for a description of the resource 148controls supported in the current release of the Solaris operating system. 149.Pp 150By default, project 151.Sy system 152(project ID 0) includes all system daemons 153started by initialization scripts and has an 154.Dq unlimited 155amount of shares. 156That 157is, it is always scheduled first no matter how many shares are given to other 158projects. 159.Pp 160The following command sets FSS as the default scheduler for the system: 161.Bd -literal -offset 2n 162# dispadmin -d FSS 163.Ed 164.Pp 165This change will take effect on the next reboot. 166Alternatively, you can move 167processes from the time-share scheduling class (as well as the special case of 168init) into the FSS class without changing your default scheduling class and 169rebooting by becoming 170.Sy root , 171and then using the 172.Xr priocntl 1 173command, as shown in the following example: 174.Bd -literal -offset 2n 175# priocntl -s -c FSS -i class TS 176# priocntl -s -c FSS -i pid 1 177.Ed 178.Sh CONFIGURING SCHEDULER WITH DISPADMIN 179You can use the 180.Xr dispadmin 8 181command to examine and tune the FSS 182scheduler's time quantum value. 183Time quantum is the amount of time that a 184thread is allowed to run before it must relinquish the processor. 185The following 186example dumps the current time quantum for the fair share scheduler: 187.Bd -literal -offset 2n 188$ dispadmin -g -c FSS 189 # 190 # Fair Share Scheduler Configuration 191 # 192 RES=1000 193 # 194 # Time Quantum 195 # 196 QUANTUM=110 197.Ed 198.Pp 199The value of the QUANTUM represents some fraction of a second with the 200fractional value determined by the reciprocal value of RES. 201With the default 202value of RES = 1000, the reciprocal of 1000 is \&.001, or milliseconds. 203Thus, by 204default, the QUANTUM value represents the time quantum in milliseconds. 205.Pp 206If you change the RES value using 207.Xr dispadmin 8 208with the 209.Fl r 210option, you also change the QUANTUM value. 211For example, instead of quantum of 110 with RES 212of 1000, a quantum of 11 with a RES of 100 results. 213The fractional unit is different while the amount of time is the same. 214.Pp 215You can use the 216.Fl s 217option to change the time quantum value. 218Note that such changes are not preserved across reboot. 219Please refer to the 220.Xr dispadmin 8 221man page for additional information. 222.Sh SEE ALSO 223.Xr prctl 1 , 224.Xr priocntl 1 , 225.Xr priocntl 2 , 226.Xr project 5 , 227.Xr resource_controls 7 , 228.Xr dispadmin 8 , 229.Xr psrset 8 230.Pp 231.%T System Administration Guide: Virtualization Using the Solaris Operating System 232