Print this page
12144 Convert Intro(7) to mandoc
12145 Convert cpr(7) to mandoc
12146 Convert ibmf(7) to mandoc
12147 Convert FSS(7) to mandoc
Reviewed by: Peter Tribble <peter.tribble@gmail.com>

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