<?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-EF73C56D-AEB1-558B-BAD1-D076BA6EA889" xml:lang="en"><title>Impact
of Data Paging on User Side Code Guide</title><shortdesc>Explains cases in which data paging degrades the performance of
user side code and sets out strategies to mitigate these effects. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-FCD37C40-C547-483C-AB65-B6465955DE70"><title>Purpose</title> <p>Data paging degrades the performance of
user side code. This document describes strategies to mitigate these effects.
It is intended for application developers whose code uses device drivers. </p> <p><b>Intended Audience:</b> </p> <p>Application developers writing modules
which involve device drivers. </p> </section>
<section id="GUID-2F31D78F-C2E9-42E1-B489-46B69A2A0AED"><title>Mitigating the impact of data paging on user side code</title> <p>Data
paging is a technique which increases the size of virtual RAM by holding data
on external media and read into physical RAM when accessed. The technique
trades off an increase in available RAM against decreased performance. Developers
must allow for the impact on performance and aim to mitigate it by using the
practices described in this document. </p> <p>Data paging is mainly a property
of processes. Processes can be configured to be paged or unpaged when they
are built or put into a ROM image. Threads and the data which they use inherit
the data paging configuration of the creating process and that configuration
can be modified at the level of the thread or the individual items of data. </p> <p><b>Thread scheduling</b> </p> <p>When a platform uses data paging there is
a higher risk of delays, timing-related defects and race conditions. </p> <p>When
a thread accesses paged memory, the required page may be paged in (actually
in RAM) or paged out (stored in media). If it is paged out, a page fault results,
slowing performance by a factor of thousands and sometimes up to a million.
The delay can also expose latent race conditions and timing-related defects
in existing code: for instance an asynchronous request to a server may appear
to complete synchronously, returning control to the client before the request
has completed with incorrect behavior as a result. </p> <p>The cure for this
problem is to configure data paging when chunks, heaps and threads are created. </p> <p>When
creating a thread of class <xref href="GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5.dita"><apiname>RThread</apiname></xref> you can call the creating
function <xref href="GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5.dita#GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5/GUID-6C840907-C3F7-34B7-97DB-CEDBA68EA277"><apiname>RThread::Create()</apiname></xref> with an argument of class <xref href="GUID-1D0D14AD-43CF-3B52-AD8D-641F75B8098C.dita"><apiname>TThreadCreateInfo</apiname></xref> as
argument. You use an instance of this class to configure the data paging attributes
to one of </p> <ul>
<li id="GUID-E4F9029C-DEF9-5305-8006-BC56EA509F72"><p> <xref href="GUID-B1A7F7DF-9A43-3C7E-8602-503B7ED5A1A1.dita"><apiname>EUnspecified</apiname></xref> (the
thread inherits the paging attributes of the creating process), </p> </li>
<li id="GUID-FC939BA1-0822-53AB-B5BC-26CCD4D77075"><p> <xref href="GUID-7B309F53-DF64-389A-8D74-394D9F16E532.dita"><apiname>EPaged</apiname></xref> (the
thread will data page its stack and heap), or </p> </li>
<li id="GUID-973FCF18-4D8D-56F2-8263-46BF47B179B5"><p> <xref href="GUID-1F1551D0-77AE-33CE-940B-A9E0C4D4881B.dita"><apiname>EUnpaged</apiname></xref> (the
thread will not data page its stack and heap). </p> </li>
</ul> <p>When creating a chunk of class <xref href="GUID-326A2F4D-0E99-31C0-A35D-E8BF45913F07.dita"><apiname>RChunk</apiname></xref> you can
call the creating function <xref href="GUID-326A2F4D-0E99-31C0-A35D-E8BF45913F07.dita#GUID-326A2F4D-0E99-31C0-A35D-E8BF45913F07/GUID-EA7C4105-6D64-3F87-83B6-C97DCDEDB94A"><apiname>RChunk::Create()</apiname></xref> with an argument
of class <xref href="GUID-51F7DBCF-BFB6-31F9-8882-5D263A1AD4B4.dita"><apiname>TChunkCreateInfo</apiname></xref> as argument. You use an instance
of this class to configure the data paging attributes to one of </p> <ul>
<li id="GUID-A5BF2717-0814-5CBD-9EA5-296890B633C6"><p> <xref href="GUID-B1A7F7DF-9A43-3C7E-8602-503B7ED5A1A1.dita"><apiname>EUnspecified</apiname></xref> (the
chunk inherits the paging attributes of the creating process), </p> </li>
<li id="GUID-FAC297A5-27A3-5BA3-94CA-64D548368132"><p> <xref href="GUID-7B309F53-DF64-389A-8D74-394D9F16E532.dita"><apiname>EPaged</apiname></xref> (the
chunk will be data paged), or </p> </li>
<li id="GUID-86BE6A49-1B9B-59C7-A90B-BF7498138714"><p> <xref href="GUID-1F1551D0-77AE-33CE-940B-A9E0C4D4881B.dita"><apiname>EUnpaged</apiname></xref> (the
chunk will not be data paged). </p> </li>
</ul> <p>The <xref href="GUID-326A2F4D-0E99-31C0-A35D-E8BF45913F07.dita"><apiname>RChunk</apiname></xref> class also has a function <xref href="GUID-D848C0BA-F931-3F95-96B3-B64133FD5928.dita"><apiname>IsPaged()</apiname></xref> to
test whether a chunk is data paged. </p> <p>When creating a chunk heap of
class <xref href="GUID-C5D0C7E7-061F-3BA5-AE24-B83237684B01.dita"><apiname>UserHeap</apiname></xref> you can call the creating function <xref href="GUID-C5D0C7E7-061F-3BA5-AE24-B83237684B01.dita#GUID-C5D0C7E7-061F-3BA5-AE24-B83237684B01/GUID-18A6B89B-4844-37E5-B46E-32188760A8C0"><apiname>UserHeap::ChunkHeap()</apiname></xref> with
an argument of class <xref href="GUID-3DCB92FB-9C74-3B73-B229-BF7944087EE9.dita"><apiname>TChunkHeapCreateInfo</apiname></xref> as argument.
You use an instance of this class to configure the data paging attributes
to one of </p> <ul>
<li id="GUID-EC970D3F-05F3-52AD-A22C-A512209569A9"><p> <xref href="GUID-B1A7F7DF-9A43-3C7E-8602-503B7ED5A1A1.dita"><apiname>EUnspecified</apiname></xref> (the
heap inherits the paging attributes of the creating process), </p> </li>
<li id="GUID-66682630-3718-5FE2-AFCC-CB6697DFFC58"><p> <xref href="GUID-7B309F53-DF64-389A-8D74-394D9F16E532.dita"><apiname>EPaged</apiname></xref> (the
heap will be data paged), or </p> </li>
<li id="GUID-6E922E2B-31EF-58C9-9083-C4590BA11FE2"><p> <xref href="GUID-1F1551D0-77AE-33CE-940B-A9E0C4D4881B.dita"><apiname>EUnpaged</apiname></xref> (the
heap will not be data paged). </p> </li>
</ul> <p><b>Inter-process
communication</b> </p> <p>Data paging impacts on inter-process communication
when a non-paged server accesses paged memory passed from a client. If the
memory being accessed is not paged in, unpredictable delays may occur, and
when the server offers performance guarantees to its clients, all the other
clients will be affected as well. There are three separate solutions to this
problem: </p> <ul>
<li id="GUID-86BB0F84-2660-5682-AA4E-B6922AF54F5F"><p>pinning memory automatically, </p> </li>
<li id="GUID-4B6D47CE-9585-5CFF-AFE2-8987FAF9899A"><p>pinning memory as requested
by the client, and </p> </li>
<li id="GUID-09AC4F78-64A0-5572-AA8A-791176807734"><p>using separate threads
for paged and unpaged clients. </p> </li>
</ul> <p>Pinning paged memory means paging it into the RAM cache (if it is
not already present) and preventing it from being paged out until it is unpinned. </p> <p>You
can set a server so that all memory passed to it by a client call gets pinned
for the duration of the call. You do so by calling the function <xref href="GUID-E5D22145-1B40-39F4-9242-72B64A0FB29C.dita"><apiname>SetPinClientDescriptors()</apiname></xref> of
a <xref href="GUID-8E316AC4-4676-301A-9A23-659E83AA1D1C.dita"><apiname>CServer2</apiname></xref> object after construction but before calling <xref href="GUID-8E316AC4-4676-301A-9A23-659E83AA1D1C.dita#GUID-8E316AC4-4676-301A-9A23-659E83AA1D1C/GUID-3B6AC8A4-251C-39A7-BFB2-30AD454DF590"><apiname>CServer2::Start()</apiname></xref> for
the first time. This method is easy but wasteful, as all memory gets pinned
not just the data needs and the performance of the paging cache is impacted.
Automatic pinning should therefore only be used as a last resort. </p> <p>You
can pin specified items of memory at the request of the client by calling
the <xref href="GUID-349EE025-F5DB-3430-9BA9-9FBF685F6B07.dita"><apiname>PinArgs()</apiname></xref> function of the <xref href="GUID-4AD02F14-1142-372F-9D11-224595932034.dita"><apiname>TIpcArgs</apiname></xref> class.
This is the more efficient method as it allows fine-grained control over what
memory is pinned. </p> <p>Separate threads for paged and unpaged clients. </p> <p><b>Thread performance</b> </p> <p>The set of pages accessed by a thread over
a given period of time is called its working set. If the working set is paged,
the performance of the thread degrades as the working set increases. When
working with paged memory it is therefore important to minimise the working
set. </p> <p>The main solution to this problem is to choose data structures
with high locality, that is data structure residing in single or adjacent
pages. An example of this is a preference for arrays rather than linked lists,
since arrays are usually in adjacent pages while the elements of linked lists
may reside on multiple pages. </p> </section>
</conbody><related-links>
<link href="GUID-E21E7992-607A-5A49-B022-189ECA9E76D1.dita"><linktext>Code Paging
Overview</linktext></link>
<link href="GUID-BDB847A2-557A-5902-AA6D-C1AE10D8E493.dita"><linktext>Code Paging
Guide</linktext></link>
<link href="GUID-B35A70D2-1BC8-51DE-95BF-F315DB394582.dita"><linktext>Demand Paging
Overview</linktext></link>
</related-links></concept>