--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-7B173E02-9697-51F4-A7E8-795AEF547109.dita	Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,177 @@
+<?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_d0e221479_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_d0e222082_href.png" placement="inline"/>
+</fig> <p>Note that we have used <i>E'</i> as an abreviation 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>
\ No newline at end of file