<?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_d0e251347_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>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_d0e251942_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>