<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-7B173E02-9697-51F4-A7E8-795AEF547109" xml:lang="en"><title>Thread
Priority Scheme</title><shortdesc>Explains the factors involved in allocating thread priority.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>At any given time, the thread running on Symbian platform is the one with
the highest priority that is ready to run. The priority of a thread is simply
a number; the value determines the priority; the greater the number, the higher
the priority. We call this the <i>true</i> or <i>absolute</i> priority of
the thread. </p>
<p>The Kernel schedules a fixed amount of time called a <i>quantum</i> for
a thread to run on the CPU, and the scheduler chooses the highest priority
thread that is ready to run. Threads of equal priority are executed on a <i>round
robin basis</i>. </p>
<p>The <i>true</i> priority values range from 0 (lowest) to 63 (highest). </p>
<p>The priority range divides into four broad categories: </p>
<table id="GUID-1EAC04DE-B68F-5F95-887C-39E9926F2500">
<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
<tbody>
<row>
<entry><p>0</p> </entry>
<entry><p>This is reserved for the <i>null thread</i>, which puts the processor
into idle mode to save power when no other threads are ready to run. </p> </entry>
</row>
<row>
<entry><p>1 - 23 </p> </entry>
<entry><p>Used by kernel side threads and user-side applications and servers </p> </entry>
</row>
<row>
<entry><p>24 -31 </p> </entry>
<entry><p>Used by kernel side threads and protected system servers, i.e. servers
with the <codeph>ProtServ</codeph> capability. </p> </entry>
</row>
<row>
<entry><p>32 - 63 </p> </entry>
<entry><p>Reserved for real-time threads running on the kernel side. </p> </entry>
</row>
</tbody>
</tgroup>
</table>
<fig id="GUID-5FFD4994-B20D-5095-8F6E-FB1151A4FF79">
<image href="GUID-A95FEDD4-106A-5E14-8B64-3E2882C76666_d0e246388_href.png" placement="inline"/>
</fig>
<ul>
<li id="GUID-2BCF03FE-C23E-5CCA-87CF-4AE9A91FD0D8"><p> <xref href="GUID-7B173E02-9697-51F4-A7E8-795AEF547109.dita#GUID-7B173E02-9697-51F4-A7E8-795AEF547109/GUID-0194B574-806B-5BA3-B65C-6DC5A80CAB86">Priority scheme for general user-side threads</xref>  </p> </li>
<li id="GUID-000499D5-EE19-5838-90CD-8C13AC468A52"><p> <xref href="GUID-7B173E02-9697-51F4-A7E8-795AEF547109.dita#GUID-7B173E02-9697-51F4-A7E8-795AEF547109/GUID-23801A52-4E62-56F4-8D81-E0A417517FDA">Priority scheme for real-time user-side threads</xref>  </p> </li>
<li id="GUID-1BA97FE4-F817-50E4-A6DA-6B0B64819811"><p> <xref href="GUID-7B173E02-9697-51F4-A7E8-795AEF547109.dita#GUID-7B173E02-9697-51F4-A7E8-795AEF547109/GUID-F5B98A28-EEDA-58BD-A6CC-62C1621D44DF">Thread priority value mapping table</xref>  </p> </li>
<li id="GUID-2BB44CDE-B566-52C0-869C-C60FB8D6AD94"><p> <xref href="GUID-7B173E02-9697-51F4-A7E8-795AEF547109.dita#GUID-7B173E02-9697-51F4-A7E8-795AEF547109/GUID-E9AFB6A3-ED3E-5110-82C8-E5E15E0AF899">Platform security notes</xref>  </p> </li>
</ul>
<section id="GUID-0194B574-806B-5BA3-B65C-6DC5A80CAB86"><title>Priority scheme
for general user-side threads</title> <p>User-side threads do not allocate <i>true</i> priority
values directly. Instead, they allocate priorities using symbolic values defined
by enums. Symbian platform maps these values to the <i>true</i> value. </p> <p>There
are two priority allocation schemes: </p> <ul>
<li id="GUID-6BE65AEC-DC54-5350-8704-538B5E425352"><p> <xref href="GUID-7B173E02-9697-51F4-A7E8-795AEF547109.dita#GUID-7B173E02-9697-51F4-A7E8-795AEF547109/GUID-B9022468-F4E7-536B-B1D4-58DAA9EA5914">Process-relative scheme</xref>  </p> </li>
<li id="GUID-BBB502EA-950C-5F8C-8CA2-F5F339000A10"><p> <xref href="GUID-7B173E02-9697-51F4-A7E8-795AEF547109.dita#GUID-7B173E02-9697-51F4-A7E8-795AEF547109/GUID-7A38EE63-E955-5432-84E1-F35CB45C931E">Process-independent scheme for general user threads</xref>  </p> </li>
</ul> <p id="GUID-B9022468-F4E7-536B-B1D4-58DAA9EA5914"><b>Process-relative scheme</b> </p> <p>This
scheme bases the <i>true</i> priority of a thread on the priority of its owning
process and the priority of the thread relative to the process. This means
that changing the process priority results in a change to the <i>true</i> priority
of the thread. </p> <p>A process can be assigned one of eight discrete priorities
represented by the individual enumerators of <xref href="GUID-5D289F30-2C88-396D-9748-798055F0AF56.dita"><apiname>TProcessPriority</apiname></xref>,
and range from <xref href="GUID-9B7922A7-6098-3BBD-9ADE-BC21AD6381C3.dita"><apiname>EPriorityLow</apiname></xref>, the lowest, to <xref href="GUID-A35268D0-7EFC-3D58-8C79-E4E619F762F5.dita"><apiname>EPrioritySupervisor</apiname></xref>,
the highest. </p> <p>In practice, <i>user processes</i> can only be assigned
priorities that are one of the values: </p> <ul>
<li id="GUID-85AA4A1D-A168-5AEF-9D4C-DC14C28686B2"><p> <xref href="GUID-9B7922A7-6098-3BBD-9ADE-BC21AD6381C3.dita"><apiname>EPriorityLow</apiname></xref> <codeph/>  </p> </li>
<li id="GUID-45B720BB-3696-545F-B966-A2EA4B37AE5D"><p> <xref href="GUID-8778A277-DA7F-34A0-8472-29226DEC2CCE.dita"><apiname>EPriorityBackground</apiname></xref>  </p> </li>
<li id="GUID-DF2708D4-B670-5B15-B587-CB71EAC99045"><p> <xref href="GUID-A62CF9B2-63E3-31E0-A51E-E04F2E2EB38F.dita"><apiname>EPriorityForeGround</apiname></xref>  </p> </li>
<li id="GUID-9C68DD95-2AB6-57D0-9966-D83144788458"><p> <xref href="GUID-8995D880-69B7-3C31-891B-7A2C57E372FE.dita"><apiname>EPriorityHigh</apiname></xref>  </p> </li>
</ul> <p>There are a further four process priorities that a user process is
not permitted to set: <codeph>EPriorityWindowServer</codeph>, <codeph>EPriorityFileServer</codeph>, <codeph>EPriorityRealTimeServer</codeph> and <codeph>EPrioritySupervisor</codeph>. </p> <p>A process priority can be assigned: </p> <ul>
<li id="GUID-CC4FA12C-BFDD-5F75-BC18-B742BCACEECF"><p>when the associated <filepath>.exe</filepath> is
built; this is done by specifying the value in the <filepath>.mmp</filepath> file
that defines the project. </p> </li>
<li id="GUID-B86220D9-B10D-5506-AD90-73E7F8D7A089"><p>by calling <xref href="GUID-9DD1EA2B-DC59-315C-8E9C-CE6D9461B695.dita#GUID-9DD1EA2B-DC59-315C-8E9C-CE6D9461B695/GUID-189A64CB-F2EA-3C8F-A7A7-01CBF8FDE67A"><apiname>RProcess::SetPriority()</apiname></xref> and
passing one of the <xref href="GUID-5D289F30-2C88-396D-9748-798055F0AF56.dita"><apiname>TProcessPriority</apiname></xref> enum values. </p> </li>
</ul> <p>See also : <xref href="GUID-8DB5E558-9774-5CC3-AF8C-6C50D9FE0496.dita">Using
Makmake</xref> in the <xref href="GUID-B21141D4-3BFE-59C9-8D5F-147A93BE1C95.dita">Build
Tools Guide</xref>. </p> <p>The priority of a thread <i>relative</i> to a
process is assigned by calling <xref href="GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5.dita#GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5/GUID-8E412361-AE54-3585-AF2A-45D4A53F8B03"><apiname>RThread::SetPriority()</apiname></xref> and
passing one of the five <xref href="GUID-8708AFB7-92CC-34FC-9FBB-E6B16472B99D.dita"><apiname>TThreadPriority</apiname></xref> enum values: </p> <ul>
<li id="GUID-BCFFB27F-5CEB-58E8-A859-C82273CB7FDC"><p> <xref href="GUID-DF41A24C-6873-37E6-834A-98CDFC8D54FB.dita"><apiname>EPriorityMuchLess</apiname></xref>  </p> </li>
<li id="GUID-21C1A24C-483D-579B-BA56-31B3694215CE"><p> <xref href="GUID-0429DE71-44B4-3764-A62B-AD937E6AD355.dita"><apiname> EPriorityLess</apiname></xref>  </p> </li>
<li id="GUID-48747F5D-8F0E-5C57-8858-35D8881B1DB7"><p> <xref href="GUID-2ACE5CF0-7E8B-35FF-8ABC-6917B2F68BB1.dita"><apiname>EPriorityNormal</apiname></xref>  </p> </li>
<li id="GUID-78DEBC15-DFD8-5384-8358-3744E2C1DDBE"><p> <xref href="GUID-34B6B121-2E45-36FE-B0FA-E8272E2F1D10.dita"><apiname>EPriorityMore</apiname></xref>  </p> </li>
<li id="GUID-AE42DA32-09CA-5C8B-B9AF-2A68E66E6218"><p> <xref href="GUID-4F19A64D-FBBE-34F2-8387-1449E49DC923.dita"><apiname> EPriorityMuchMore</apiname></xref>  </p> </li>
</ul> <p>The <xref href="GUID-7B173E02-9697-51F4-A7E8-795AEF547109.dita#GUID-7B173E02-9697-51F4-A7E8-795AEF547109/GUID-F5B98A28-EEDA-58BD-A6CC-62C1621D44DF">thread
priority value mapping table</xref> shows the <i>true</i> priority of a thread
based on the combination of process priority and process-relative thread priority </p> <p id="GUID-7A38EE63-E955-5432-84E1-F35CB45C931E"><b>Process-independent scheme
for general user threads</b> </p> <p>In this scheme, the <i>true</i> priority
of a thread is independent of the priority of its owning process. Changing
the priority of the underlying process has no effect on the <i>true</i> priority
of the thread. </p> <p>The priority of a thread is assigned by calling <xref href="GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5.dita#GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5/GUID-8E412361-AE54-3585-AF2A-45D4A53F8B03"><apiname>RThread::SetPriority()</apiname></xref> and
passing one of the <xref href="GUID-8708AFB7-92CC-34FC-9FBB-E6B16472B99D.dita"><apiname>TThreadPriority</apiname></xref> enum values listed below.
Note that the set of enum values splits into two logical groupings based on
their equivalence to process-relative values. See the <xref href="GUID-7B173E02-9697-51F4-A7E8-795AEF547109.dita#GUID-7B173E02-9697-51F4-A7E8-795AEF547109/GUID-F5B98A28-EEDA-58BD-A6CC-62C1621D44DF">thread priority value mapping table</xref>. </p> <table id="GUID-A0397BB8-AAC7-5F79-B94F-68103B66132C">
<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
<tbody>
<row>
<entry><p> <b> Group 1 </b>  </p> </entry>
<entry><p> <b> Group 2 </b>  </p> </entry>
</row>
<row>
<entry><ul>
<li id="GUID-12430992-C96F-5006-85AD-A9308AB75B93"><p> <xref href="GUID-A131F0B9-C8D4-3F0D-A0CB-140DA8EA3288.dita"><apiname>EPriorityAbsoluteVeryLow</apiname></xref>  </p> </li>
<li id="GUID-A5682ECF-DCAA-5E35-8294-613A30F416FD"><p> <xref href="GUID-280BFA0F-9A1C-3644-AF1C-B169B09D8834.dita"><apiname>EPriorityAbsoluteLow</apiname></xref>  </p> </li>
<li id="GUID-1750EB5D-A22B-5838-9EB8-37B06A0D1F98"><p> <xref href="GUID-ECA0DFF8-106C-3D1C-963C-10708885797A.dita"><apiname>EPriorityAbsoluteBackground</apiname></xref>  </p> </li>
<li id="GUID-A83FCD79-3B4C-51CC-A82A-BE8AAB9BEEC0"><p> <xref href="GUID-451D6DB5-C247-34BF-8D8A-288C03599B7E.dita"><apiname>EPriorityAbsoluteForeground</apiname></xref>  </p> </li>
<li id="GUID-1EDD4765-F02A-56CD-882D-E4DD443CE410"><p> <xref href="GUID-B6EEA9DD-68AE-30FD-AEE1-9B227109750F.dita"><apiname>EPriorityAbsoluteHigh</apiname></xref>  </p> </li>
</ul> </entry>
<entry><ul>
<li id="GUID-E03FCF50-F5B6-5885-B939-88B513F4AC2F"><p> <xref href="GUID-0070BA48-851D-36E2-9C4C-C11C0FF0BE46.dita"><apiname>EPriorityAbsoluteLowNormal</apiname></xref>  </p> </li>
<li id="GUID-4C94D1D2-6B81-57D8-B44D-2FE19E9971F9"><p> <xref href="GUID-CD20880F-21EB-389C-A0A4-8DFFE714B102.dita"><apiname>EPriorityAbsoluteBackgroundNormal</apiname></xref>  </p> </li>
<li id="GUID-6D3AA39B-AE42-575A-B63B-D109049ABFEF"><p> <xref href="GUID-1054385C-7168-31ED-89D9-4C33E28836A0.dita"><apiname>EPriorityAbsoluteForegroundNormal</apiname></xref>  </p> </li>
<li id="GUID-E41572FD-0C50-54BC-98C6-857A8D86CCD7"><p> <xref href="GUID-E49C7DFA-4604-310C-915C-F278382A796A.dita"><apiname>EPriorityAbsoluteHighNormal</apiname></xref>  </p> </li>
</ul> </entry>
</row>
</tbody>
</tgroup>
</table> <p>The <xref href="GUID-7B173E02-9697-51F4-A7E8-795AEF547109.dita#GUID-7B173E02-9697-51F4-A7E8-795AEF547109/GUID-F5B98A28-EEDA-58BD-A6CC-62C1621D44DF">thread
priority value mapping table</xref> shows the resulting <i>true</i> priority
of the thread. </p> </section>
<section id="GUID-23801A52-4E62-56F4-8D81-E0A417517FDA"><title>Priority scheme
for real-time user-side threads</title> <p>This scheme is the same as the <xref href="GUID-7B173E02-9697-51F4-A7E8-795AEF547109.dita#GUID-7B173E02-9697-51F4-A7E8-795AEF547109/GUID-7A38EE63-E955-5432-84E1-F35CB45C931E">process-independent
scheme for general user threads</xref>, but with one essential difference
- the range of <xref href="GUID-8708AFB7-92CC-34FC-9FBB-E6B16472B99D.dita"><apiname>TThreadPriority</apiname></xref> enum values to be passed
to <xref href="GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5.dita#GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5/GUID-8E412361-AE54-3585-AF2A-45D4A53F8B03"><apiname>RThread::SetPriority()</apiname></xref> is as shown below. These priorities
map to the <i>true</i> priority values in the range 24 -31, and can only be
set by executables having the <codeph>ProtServ</codeph> capability. This range
is referred to as the real time range. </p> <ul>
<li id="GUID-78ACFC22-4FB7-5E90-B6E2-9EF39EA9A3F5"><p> <xref href="GUID-7574A754-ED28-3FE1-85BB-93F110DE8E50.dita"><apiname>EPriorityAbsoluteRealTime1</apiname></xref>  </p> </li>
<li id="GUID-3ADBFE8D-E7D9-5316-B06E-E3C514F4221E"><p> <xref href="GUID-2561145A-9506-31F5-A0EA-24609EC71412.dita"><apiname>EPriorityAbsoluteRealTime2</apiname></xref>  </p> </li>
<li id="GUID-90F0E400-AB37-52CC-B01E-2D7C3E589111"><p> <xref href="GUID-39A7F794-B7B1-3C0C-AFFF-956C71CE529F.dita"><apiname>EPriorityAbsoluteRealTime3</apiname></xref>  </p> </li>
<li id="GUID-DDB4B69C-9BBD-5E4B-B87C-CF52B4BDAA85"><p> <xref href="GUID-DCDD7812-10F8-35A1-9DAD-EFDAC6EA874B.dita"><apiname> EPriorityAbsoluteRealTime4</apiname></xref>  </p> </li>
<li id="GUID-91DEE716-6F45-51C2-8139-B9CB1AE5065B"><p> <xref href="GUID-F3872848-57CA-3682-80E2-39E87B7B3656.dita"><apiname>EPriorityAbsoluteRealTime5</apiname></xref>  </p> </li>
<li id="GUID-01B2B0B9-4242-5D8E-83B2-2658CF68548F"><p> <xref href="GUID-D3FE9747-0CD8-3E0A-829E-3D7184AE8431.dita"><apiname>EPriorityAbsoluteRealTime6</apiname></xref>  </p> </li>
<li id="GUID-6581842F-C83C-53A5-A567-F1D4BE97488C"><p> <xref href="GUID-A6BF84AA-2421-3DB0-A30D-B9D3B7E70B21.dita"><apiname>EPriorityAbsoluteRealTime7</apiname></xref>  </p> </li>
<li id="GUID-C7AB328B-B910-51D2-ADB0-5E8A33AFCD69"><p> <xref href="GUID-84C4AED5-8AA8-31F0-9E77-6BBACE192763.dita"><apiname>EPriorityAbsoluteRealTime8</apiname></xref>  </p> </li>
</ul> <p>The <xref href="GUID-7B173E02-9697-51F4-A7E8-795AEF547109.dita#GUID-7B173E02-9697-51F4-A7E8-795AEF547109/GUID-F5B98A28-EEDA-58BD-A6CC-62C1621D44DF">thread
priority value mapping table</xref> shows the resulting <i>true</i> priority
of the thread. </p> </section>
<section id="GUID-F5B98A28-EEDA-58BD-A6CC-62C1621D44DF"><title>Thread priority
value mapping table</title> <p>This table shows the effect of setting priorities,
and the resulting <i>true</i> priority values. You need to be aware that this
may change in the future, and you should never synchronise threads on the
basis of thread priorities. If you need to synchronise threads, use mutexes
or semaphores. </p> <p>Notes </p> <ul>
<li id="GUID-CBC69A23-E3EF-56BC-A915-2770EBFB76C4"><p>True priority values
in the shaded region can only be accessed by threads running in processes
with the <codeph>ProtServ</codeph> capability. </p> </li>
<li id="GUID-1F8FC263-3C39-5E3C-A186-6D5D4DF7D6D3"><p>The process-priority
values : <xref href="GUID-972ADC0C-546E-3D24-9071-02B074DC1540.dita"><apiname>EPriorityWindowServer</apiname></xref>, <xref href="GUID-A19C5464-A1DA-3EEC-B81B-41690EBB3DB2.dita"><apiname>EPriorityFileServer</apiname></xref> and <xref href="GUID-A35268D0-7EFC-3D58-8C79-E4E619F762F5.dita"><apiname>EPrioritySupervisor</apiname></xref> all
map to the same range of priorities. Along with <xref href="GUID-AAA610A8-48D8-3642-94E8-6C9747170DA9.dita"><apiname>EPriorityRealTimeServer</apiname></xref>,
these have historically been used for system servers and other processes needing
access to high priorities suitable for real-time tasks, and their use requires <codeph>ProtServ</codeph> capability. </p> </li>
<li id="GUID-3256F08A-AD30-5378-BFA9-140688B1CDB6"><p>Note that <codeph>ProtServ</codeph> capability
will not be granted to general applications for the purpose of gaining access
to the very high thread priorities. This risks breaking important system functionality. </p> </li>
</ul> <fig id="GUID-6BF93712-F8AA-5D08-A5D4-FEB6B22592D8">
<image href="GUID-B9306D01-1DE5-511A-AC1A-6E3E9749BA89_d0e246991_href.png" placement="inline"/>
</fig> <p>Note that we have used <i>E'</i> as an abbreviation for <i>EPriority</i> in
this diagram. </p> </section>
<section id="GUID-E9AFB6A3-ED3E-5110-82C8-E5E15E0AF899"><title>Platform security
notes</title> <p>Platform security restrictions prevent thread and process
priorities from being modified by another user process. There is one exception:
by default, applications have “Priority Control” enabled for them which allows
the window server to switch them between foreground and background process
priorities depending on which has foreground focus. </p> </section>
</conbody></concept>