--- a/Symbian3/SDK/Source/GUID-A64625D4-F101-5DB7-896B-F91A21BABE01.dita	Fri Jul 16 17:23:46 2010 +0100
+++ b/Symbian3/SDK/Source/GUID-A64625D4-F101-5DB7-896B-F91A21BABE01.dita	Tue Jul 20 12:00:49 2010 +0100
@@ -1,12 +1,127 @@
-<?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 xml:lang="en" id="GUID-A64625D4-F101-5DB7-896B-F91A21BABE01"><title>Reclaiming Free Space</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>This document discusses the benefits to be had, such as performance improvements, from performing a <b>compaction</b> operation. </p> <section><title>Purpose</title> <p>Database compaction frees up diskspace and improves overall performance when performing certain database operations. </p> </section> <section id="GUID-E7319024-5988-5398-8F77-FAD6F644D1DB"><title>Database compaction</title> <p>Databases using database compaction will experience a performance improvement for some operations, such as DELETE. There will also be a better trade-off between performance and disk usage. </p> <p>Legacy databases will be automatically migrated to use the new default free space reclaim policy when they are used with the 9.5 version of Symbian SQL. The migration takes place the first time the legacy database is opened with the new version of Symbian SQL. The database will be configured to use the default free space reclaim policy from then on. <b>Note</b>: Such migration will not be possible (or necessary) for databases that are on read-only media, but these databases will still be readable by Symbian SQL. </p> <p>Databases can be configured to use a free space reclaim policy of their choice. There are three modes of database compaction: </p> <ul><li id="GUID-7394A159-1BFA-53FF-ABBB-50D1DC8453F0"><p> <xref href="GUID-A64625D4-F101-5DB7-896B-F91A21BABE01.dita#GUID-A64625D4-F101-5DB7-896B-F91A21BABE01/GUID-4AF5A27E-9793-5931-B2D0-3673B556DB6D">background</xref>, </p> </li> <li id="GUID-DCA4B080-B17B-5AFB-916A-9B84C1C3DC5E"><p> <xref href="GUID-A64625D4-F101-5DB7-896B-F91A21BABE01.dita#GUID-A64625D4-F101-5DB7-896B-F91A21BABE01/GUID-CE6F567F-7300-574A-A180-E42786DC04DB">synchronous</xref>, </p> </li> <li id="GUID-72035C8D-9B12-5EDB-BD3D-59762DFB46B9"><p> <xref href="GUID-A64625D4-F101-5DB7-896B-F91A21BABE01.dita#GUID-A64625D4-F101-5DB7-896B-F91A21BABE01/GUID-F9D40D87-B383-5EF5-9959-2A344436477A">manual</xref>. </p> </li> </ul> <p>The compaction mode is set when the database is created and cannot be changed later. Only the database creator can specify the compaction mode. This avoids the possibility of conflicting policy change requests by clients of shared databases. When a database compaction mode is not specified, background mode is the default mode. </p> <p id="GUID-4AF5A27E-9793-5931-B2D0-3673B556DB6D"><b>Background compaction</b> </p> <p>Compaction activities are deferred and scheduled by the server allowing client requests that delete records to complete more quickly. This mode offers clients no guarantees on when space will be reclaimed. When under high load the server will defer reclamation indefinitely. </p> <p>The server maintains an <xref href="GUID-4000D46C-29C0-3497-8E20-FFC908670EC8.dita"><apiname>EPriorityIdle</apiname></xref> active object for each open database that is set to background compaction mode. </p> <p>The amount of reclaimable disk space is retrieved after an SQL statement is executed on a database. If this value exceeds the compaction threshold then the database is marked as <i>dirty</i> by setting its active object as ready to run: </p> <ul><li id="GUID-93948590-87D5-541A-99FE-F166656E85B1"><p> The compaction threshold is a server-wide parameter that specifies the amount of reclaimable disk space (in bytes) that must exist in a database before the server compacts that database. A default value for this threshold is supplied by Symbian but device creators can override this in the server configuration file.  </p> </li> <li id="GUID-C5E412DF-E015-592D-8BF9-16D2E82E5514"><p>Each active object contains a <i>free pages</i> threshold that is derived from the compaction threshold. The <i>free pages</i> threshold is the number of pages that must be in the database for it to be marked as <i>dirty</i>. </p> </li> <li id="GUID-2B3A1FEB-C351-5CA9-870D-F87051A36476"><p>Each time a <xref href="GUID-4688F6B7-E1B0-37CF-BAA2-C6BD103D4FDF.dita#GUID-4688F6B7-E1B0-37CF-BAA2-C6BD103D4FDF/GUID-6D2120DC-C193-3E2E-A802-B4CD180BDF11"><apiname>RSqlDatabase::Exec()</apiname></xref> or <xref href="GUID-0176BF07-DF94-3259-8F90-DE030E35CE9A.dita#GUID-0176BF07-DF94-3259-8F90-DE030E35CE9A/GUID-52E3CE72-D495-388F-8829-952E32F0F37D"><apiname>RSqlStatement::Exec()</apiname></xref> operation has been completed the number of free pages in the database is checked against the free pages threshold. If the threshold is met then the database is marked as <i>dirty</i>. </p> </li> </ul> <p>Whenever the Symbian SQL server is idle (not processing a client request) runnable idle active objects are processed that cause free space to be reclaimed from the dirty databases: </p> <ul><li id="GUID-D82FD580-ECDA-5449-BC40-C016723D7510"><p> Each active object reclaims no more pages from its database than the single reclaim limit. This limit is a server-wide parameter specifying the maximum number of free pages that the server will attempt to reclaim in one step and should be small enough to ensure that the server can remain responsive to client requests. An appropriate default value is supplied by Symbian but device creators can override this in the server configuration file.  </p> </li> <li id="GUID-84319C82-076C-5EA8-AF5D-F6D907678254"><p>Following the reclaim action an active object will again set itself as ready to run if the number of free pages following the reclaim meets the free pages threshold. </p> </li> <li id="GUID-F10B583B-F098-542D-9D6F-0F8A63A08CD0"><p>The idle priority active objects for background compaction continues to be processed until either: </p> <ul><li id="GUID-21EE7484-817C-5EEF-80F1-0600440FD74A"><p>there is no more free space left to reclaim, </p> </li> <li id="GUID-AA4694AB-D403-5807-9CC9-3608F9E86246"><p>a higher priority active object becomes ready to run. </p> </li> </ul> </li> </ul> <p><b>Scheduling of background compaction</b> </p> <p>The server’s active scheduler maintains a priority queue for servicing the active objects. The scheduling algorithm is such that following the successful execution of any active object's <codeph>RunL()</codeph>, the scheduler will reset to the beginning of the queue. This has two implications: </p> <ul><li id="GUID-CF778079-5E0F-5D74-9A8A-5DB69E4B5B00"><p>There is an implicit priority scheme among the active objects for background compaction – a database opened earlier will always be given priority over one opened later due to its location in the queue. </p> </li> <li id="GUID-9EECC098-FC0A-5DB7-8A88-FB59C826582E"><p>Compaction of a later database in the queue cannot begin until an earlier database has been fully compacted. This is because the active scheduler resets to the beginning of the queue following every active object execution. </p> </li> </ul> <p>With this lack of <i>fair scheduling</i> it is advised that certain situations are avoided: </p> <ul><li id="GUID-EAE8BC01-15F8-5A8E-99A6-48F4AB73AD68"><p>Background compaction is not intended to be an antidote for critical disk space rescue scenarios – a fairer scheduling algorithm may help but the system would already be in severe difficulties by this stage. </p> </li> <li id="GUID-D17C590B-31E4-582E-A07B-AA411B123BA2"><p>The compaction operation itself requires free disk space and thus would be inoperable in critically low disk space situations. Thus a fairer scheduling algorithm would not help here. </p> </li> <li id="GUID-80E5F115-4602-5B56-AEAC-B4490992101F"><p>background compaction is not designed to work efficiently when the server load is such that idle periods do not occur in sufficient quantity. </p> </li> </ul> <p id="GUID-CE6F567F-7300-574A-A180-E42786DC04DB"><b>Synchronous compaction</b> </p> <p>compaction occurs at the end of the client request. A request is not completed until compaction has finished. This mode is equivalent to the compaction profile of previous versions of Symbian SQL. </p> <p id="GUID-F9D40D87-B383-5EF5-9959-2A344436477A"><b>Manual compaction</b> </p> <p>No automatic compaction occurs. This mode is intended for clients that wish to manage compaction directly. </p> <p>Clients wishing to exercise direct control over database compaction may select manual mode. The server performs no automated compaction in manual mode. </p> <p>Clients can request database compaction with <xref href="GUID-4688F6B7-E1B0-37CF-BAA2-C6BD103D4FDF.dita#GUID-4688F6B7-E1B0-37CF-BAA2-C6BD103D4FDF/GUID-6F94DDD2-2586-3DEC-B5E6-B74C3A7E6DB5"><apiname>RSqlDatabase::Compact()</apiname></xref>. The client can specify a limit to the number of bytes to reclaim. Compaction can be performed as either a synchronous or an asynchronous operation. <codeph>Compact()</codeph> can be called on either a “manual” or a “background” database (it can also be called on a “synchronous” database although this will have no effect). </p> <p>The database file size and the amount of reclaimable free space in the database can be retrieved with <xref href="GUID-4688F6B7-E1B0-37CF-BAA2-C6BD103D4FDF.dita#GUID-4688F6B7-E1B0-37CF-BAA2-C6BD103D4FDF/GUID-F45D9371-F212-3D62-877A-3C31C4F49CA0"><apiname>RSqlDatabase::Size()</apiname></xref>. This API supports clients wishing to trigger compaction based on either absolute free space or a proportion of free space in the database. </p> </section> </conbody><related-links><link href="GUID-22844C28-AB5B-5A6F-8863-7269464684B4.dita"><linktext>SQL Overview</linktext> </link> <link><linktext/></link><link href="GUID-4EE4E79E-F6D5-5F14-BA8D-4DD10D229B74.dita"><linktext>Handling Blobs</linktext> </link> </related-links></concept>
\ No newline at end of file
+<?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-A64625D4-F101-5DB7-896B-F91A21BABE01" xml:lang="en"><title>Reclaiming Free Space</title><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p>This document discusses the benefits to be had, such as performance
+improvements, from performing a <b>compaction</b> operation. </p>
+<section id="GUID-9719243A-8391-4B2B-9462-65BF4F2755E7"><title>Purpose</title> <p>Database compaction frees up diskspace
+and improves overall performance when performing certain database
+operations. </p> </section>
+<section id="GUID-E7319024-5988-5398-8F77-FAD6F644D1DB"><title>Database
+compaction</title> <p>Databases using database compaction will experience
+a performance improvement for some operations, such as DELETE. There
+will also be a better trade-off between performance and disk usage. </p> <p>Legacy databases will be automatically migrated to use the new
+default free space reclaim policy when they are used with the 9.5
+version of Symbian SQL. The migration takes place the first time the
+legacy database is opened with the new version of Symbian SQL. The
+database will be configured to use the default free space reclaim
+policy from then on. <b>Note</b>: Such migration will not be possible
+(or necessary) for databases that are on read-only media, but these
+databases will still be readable by Symbian SQL. </p> <p>Databases
+can be configured to use a free space reclaim policy of their choice.
+There are three modes of database compaction: </p> <ul>
+<li id="GUID-7394A159-1BFA-53FF-ABBB-50D1DC8453F0"><p> <xref href="GUID-A64625D4-F101-5DB7-896B-F91A21BABE01.dita#GUID-A64625D4-F101-5DB7-896B-F91A21BABE01/GUID-4AF5A27E-9793-5931-B2D0-3673B556DB6D">background</xref>, </p> </li>
+<li id="GUID-DCA4B080-B17B-5AFB-916A-9B84C1C3DC5E"><p> <xref href="GUID-A64625D4-F101-5DB7-896B-F91A21BABE01.dita#GUID-A64625D4-F101-5DB7-896B-F91A21BABE01/GUID-CE6F567F-7300-574A-A180-E42786DC04DB">synchronous</xref>, </p> </li>
+<li id="GUID-72035C8D-9B12-5EDB-BD3D-59762DFB46B9"><p> <xref href="GUID-A64625D4-F101-5DB7-896B-F91A21BABE01.dita#GUID-A64625D4-F101-5DB7-896B-F91A21BABE01/GUID-F9D40D87-B383-5EF5-9959-2A344436477A">manual</xref>. </p> </li>
+</ul> <p>The compaction mode is set when the database is created and
+cannot be changed later. Only the database creator can specify the
+compaction mode. This avoids the possibility of conflicting policy
+change requests by clients of shared databases. When a database compaction
+mode is not specified, background mode is the default mode. </p> <p id="GUID-4AF5A27E-9793-5931-B2D0-3673B556DB6D"><b>Background compaction</b> </p> <p>Compaction activities are deferred and scheduled by the
+server allowing client requests that delete records to complete more
+quickly. This mode offers clients no guarantees on when space will
+be reclaimed. When under high load the server will defer reclamation
+indefinitely. </p> <p>The server maintains an <xref href="GUID-4000D46C-29C0-3497-8E20-FFC908670EC8.dita"><apiname>EPriorityIdle</apiname></xref> active object for each open database that is set to background compaction
+mode. </p> <p>The amount of reclaimable disk space is retrieved after
+an SQL statement is executed on a database. If this value exceeds
+the compaction threshold then the database is marked as <i>dirty</i> by setting its active object as ready to run: </p> <ul>
+<li id="GUID-93948590-87D5-541A-99FE-F166656E85B1"><p> The compaction
+threshold is a server-wide parameter that specifies the amount of
+reclaimable disk space (in bytes) that must exist in a database before
+the server compacts that database. A default value for this threshold
+is supplied by Symbian but device creators can override this in the
+server configuration file.  </p> </li>
+<li id="GUID-C5E412DF-E015-592D-8BF9-16D2E82E5514"><p>Each active
+object contains a <i>free pages</i> threshold that is derived from
+the compaction threshold. The <i>free pages</i> threshold is the number
+of pages that must be in the database for it to be marked as <i>dirty</i>. </p> </li>
+<li id="GUID-2B3A1FEB-C351-5CA9-870D-F87051A36476"><p>Each time a <xref href="GUID-4688F6B7-E1B0-37CF-BAA2-C6BD103D4FDF.dita#GUID-4688F6B7-E1B0-37CF-BAA2-C6BD103D4FDF/GUID-6D2120DC-C193-3E2E-A802-B4CD180BDF11"><apiname>RSqlDatabase::Exec()</apiname></xref> or <xref href="GUID-0176BF07-DF94-3259-8F90-DE030E35CE9A.dita#GUID-0176BF07-DF94-3259-8F90-DE030E35CE9A/GUID-52E3CE72-D495-388F-8829-952E32F0F37D"><apiname>RSqlStatement::Exec()</apiname></xref> operation has been completed the number of free pages in the database
+is checked against the free pages threshold. If the threshold is met
+then the database is marked as <i>dirty</i>. </p> </li>
+</ul> <p>Whenever the Symbian SQL server is idle (not processing a
+client request) runnable idle active objects are processed that cause
+free space to be reclaimed from the dirty databases: </p> <ul>
+<li id="GUID-D82FD580-ECDA-5449-BC40-C016723D7510"><p> Each active
+object reclaims no more pages from its database than the single reclaim
+limit. This limit is a server-wide parameter specifying the maximum
+number of free pages that the server will attempt to reclaim in one
+step and should be small enough to ensure that the server can remain
+responsive to client requests. An appropriate default value is supplied
+by Symbian but device creators can override this in the server configuration
+file.  </p> </li>
+<li id="GUID-84319C82-076C-5EA8-AF5D-F6D907678254"><p>Following the
+reclaim action an active object will again set itself as ready to
+run if the number of free pages following the reclaim meets the free
+pages threshold. </p> </li>
+<li id="GUID-F10B583B-F098-542D-9D6F-0F8A63A08CD0"><p>The idle priority
+active objects for background compaction continues to be processed
+until either: </p> <ul>
+<li id="GUID-21EE7484-817C-5EEF-80F1-0600440FD74A"><p>there is no
+more free space left to reclaim, </p> </li>
+<li id="GUID-AA4694AB-D403-5807-9CC9-3608F9E86246"><p>a higher priority
+active object becomes ready to run. </p> </li>
+</ul> </li>
+</ul> <p><b>Scheduling of background compaction</b> </p> <p>The server’s active
+scheduler maintains a priority queue for servicing the active objects.
+The scheduling algorithm is such that following the successful execution
+of any active object's <codeph>RunL()</codeph>, the scheduler will
+reset to the beginning of the queue. This has two implications: </p> <ul>
+<li id="GUID-CF778079-5E0F-5D74-9A8A-5DB69E4B5B00"><p>There is an
+implicit priority scheme among the active objects for background compaction
+– a database opened earlier will always be given priority over one
+opened later due to its location in the queue. </p> </li>
+<li id="GUID-9EECC098-FC0A-5DB7-8A88-FB59C826582E"><p>Compaction of
+a later database in the queue cannot begin until an earlier database
+has been fully compacted. This is because the active scheduler resets
+to the beginning of the queue following every active object execution. </p> </li>
+</ul> <p>With this lack of <i>fair scheduling</i> it is advised that
+certain situations are avoided: </p> <ul>
+<li id="GUID-EAE8BC01-15F8-5A8E-99A6-48F4AB73AD68"><p>Background compaction
+is not intended to be an antidote for critical disk space rescue scenarios
+– a fairer scheduling algorithm may help but the system would already
+be in severe difficulties by this stage. </p> </li>
+<li id="GUID-D17C590B-31E4-582E-A07B-AA411B123BA2"><p>The compaction
+operation itself requires free disk space and thus would be inoperable
+in critically low disk space situations. Thus a fairer scheduling
+algorithm would not help here. </p> </li>
+<li id="GUID-80E5F115-4602-5B56-AEAC-B4490992101F"><p>background compaction
+is not designed to work efficiently when the server load is such that
+idle periods do not occur in sufficient quantity. </p> </li>
+</ul> <p id="GUID-CE6F567F-7300-574A-A180-E42786DC04DB"><b>Synchronous compaction</b> </p> <p>compaction occurs at the end of the client request. A request
+is not completed until compaction has finished. This mode is equivalent
+to the compaction profile of previous versions of Symbian SQL. </p> <p id="GUID-F9D40D87-B383-5EF5-9959-2A344436477A"><b>Manual compaction</b> </p> <p>No automatic compaction occurs. This mode is intended for
+clients that wish to manage compaction directly. </p> <p>Clients wishing
+to exercise direct control over database compaction may select manual
+mode. The server performs no automated compaction in manual mode. </p> <p>Clients can request database compaction with <xref href="GUID-4688F6B7-E1B0-37CF-BAA2-C6BD103D4FDF.dita#GUID-4688F6B7-E1B0-37CF-BAA2-C6BD103D4FDF/GUID-6F94DDD2-2586-3DEC-B5E6-B74C3A7E6DB5"><apiname>RSqlDatabase::Compact()</apiname></xref>. The client can specify a limit to the number of bytes to reclaim.
+Compaction can be performed as either a synchronous or an asynchronous
+operation. <codeph>Compact()</codeph> can be called on either a “manual”
+or a “background” database (it can also be called on a “synchronous”
+database although this will have no effect). </p> <p>The database
+file size and the amount of reclaimable free space in the database
+can be retrieved with <xref href="GUID-4688F6B7-E1B0-37CF-BAA2-C6BD103D4FDF.dita#GUID-4688F6B7-E1B0-37CF-BAA2-C6BD103D4FDF/GUID-F45D9371-F212-3D62-877A-3C31C4F49CA0"><apiname>RSqlDatabase::Size()</apiname></xref>. This
+API supports clients wishing to trigger compaction based on either
+absolute free space or a proportion of free space in the database. </p> </section>
+</conbody><related-links>
+<link href="GUID-22844C28-AB5B-5A6F-8863-7269464684B4.dita"><linktext>SQL
+Overview</linktext></link>
+<link href="GUID-4EE4E79E-F6D5-5F14-BA8D-4DD10D229B74.dita">
+<linktext>Handling Blobs</linktext></link>
+</related-links></concept>
\ No newline at end of file