--- a/Symbian3/PDK/Source/GUID-30CAE438-6CC7-5532-8727-781B8E83574A.dita Tue Jul 20 12:00:49 2010 +0100
+++ b/Symbian3/PDK/Source/GUID-30CAE438-6CC7-5532-8727-781B8E83574A.dita Fri Aug 13 16:47:46 2010 +0100
@@ -1,116 +1,116 @@
-<?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-30CAE438-6CC7-5532-8727-781B8E83574A" xml:lang="en"><title>Heap
-Locking in the Font and Bitmap Server </title><shortdesc>The Font and Bitmap Server's heap locking API is deprecated in
-Symbian OS v9.3 and later versions. This topic explains the rationale for
-this and how it affects existing applications that use the <codeph>CFBsBitmap::LockHeap()</codeph>, <codeph>CFBsBitmap::LockHeapLC()</codeph> and <codeph>CFbsBitmap::UnlockHeap()</codeph> functions. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
-<section><title>Heap locking in previous versions </title> <p>Prior to Symbian
-OS v9.3, the Font and Bitmap Server made a distinction between small bitmaps
-and large bitmaps. The data for large bitmaps was stored in a separate global
-memory heap where a de-fragmentation algorithm was used. When necessary, this
-algorithm moved bitmap data in the virtual address space. As a result it was
-possible for an application to allocate a new bitmap and trigger the de-fragmentation
-algorithm while an unrelated application accessed the data of another bitmap.
-From an application's point of view, this meant that the value returned by <codeph>CFbsBitmap::DataAddress()</codeph> could
-change unpredictably at any time. </p> <p>The solution was to lock the global
-memory heap by calling <codeph>CFbsBitmap::LockHeap()</codeph> or <codeph>CFbsBitmap::LockHeapLC()</codeph> before
-calling <codeph>CFbsBitmap::DataAddress()</codeph>. When the application finished
-accessing the bitmap data, it unlocked the global memory heap by calling <codeph>CFbsBitmap::UnlockHeap().</codeph> Internally
-the Font and Bitmap Server used a global mutual exclusion object to implement
-the heap locking functions and waited on it before performing any operation
-that could trigger the de-fragmentation algorithm. </p> <p>Although it was
-undocumented functionality, multi-threaded applications could use the heap
-locking functions as a way of synchronizing access to bitmaps shared among
-several threads, because calls to <codeph>CFbsBitmap::LockHeap()</codeph> and <codeph>CFbsBitmap::UnlockHeap()</codeph> translated
-into <codeph>Wait()</codeph> and <codeph>Signal()</codeph> operations on the
-global mutual exclusion object. </p> </section>
-<section><title>Removal of heap locking </title> <p><b>Use of a disconnected
-memory chunk </b> </p> <p>From Symbian OS v9.3, all bitmap data is kept in
-a disconnected global memory chunk. This is a new type of chunk that does
-not require the set of pages committed to physical memory to form a contiguous
-block in the virtual address space. A virtual address range much bigger than
-the amount of physical memory is reserved, and pages are committed to physical
-memory when allocating bitmaps and de-committed when freeing them. </p> <p>As
-a result, fragmentation in the reserved virtual address range is not a problem
-and fragmentation in the physical address space is handled transparently by
-the Memory Management Unit (MMU). Therefore, de-fragmentation is not necessary
-and bitmap operations do not need to move data belonging to other bitmaps. </p> <p><b>Removal
-of in-place operations </b> </p> <p>Some bitmap operations, such as <codeph>CFbsBitmap::Resize()</codeph>, <codeph>CFbsBitmap::Compress()</codeph> and <codeph>CFbsBitmap::CompressInBackground()</codeph>, can change the
-value returned by <codeph>CFbsBitmap::DataAddress()</codeph> because they
-may need to re-allocate memory. These functions have a new implementation.
-They now create a new bitmap object inside the Font and Bitmap Server and
-update the reference contained in the <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> object.
-The old bitmap is destroyed immediately if it is referenced only by the <codeph>CFbsBitmap</codeph> object
-on which the re-allocating function was called. Otherwise, the old bitmap
-is flagged as <b>dirty</b> and its destruction is deferred until its reference
-count becomes zero. </p> <p>All of the functions in the <codeph>CFbsBitmap</codeph> class
-now check whether the referenced bitmap is dirty before proceeding. If it
-is, the Font and Bitmap Server updates the reference to point to the new bitmap.
-When all of the <codeph>CFbsBitmap</codeph> objects that referenced the old
-bitmap have had their references updated or have been deleted, the reference
-count of the old bitmap becomes zero and it is destroyed. </p> <p>The impact
-on performance of this change is negligible, because the dirty flag is tested
-in the context of the client thread and in most cases bitmaps are "clean". </p> <p>Sometimes
-multiple <codeph>CFbsBitmap</codeph> objects in different client threads reference
-the same bitmap. When a client thread calls a re-allocating function on a
-bitmap while another client thread is accessing the bitmap data through a
-pointer returned by <codeph>CFbsBitmap::DataAddress()</codeph>, there is no
-illegal memory access because the old bitmap still exists. This scenario typically
-occurs when an application calls <codeph>CFbsBitmap::CompressInBackground()</codeph> on
-a bitmap and continues to use it, because the compression is performed asynchronously
-at an unspecified time. </p> <p><b>Deprecation of the heap locking functions </b> </p> <p>The
-use of a disconnected memory chunk and the removal of in-place operations
-allow the Font and Bitmap Server to work without heap locking. Therefore, <codeph>CFbsBitmap::LockHeap()</codeph>, <codeph>CFbsBitmap::UnlockHeap()</codeph> and <codeph>CFbsBitmap::LockHeapLC()</codeph> are no longer necessary and
-have been deprecated.<b> These functions no longer provide any locking functionality
-and cannot be used as a synchronization mechanism</b>. </p> <p>It is recommended
-that you replace all calls to <codeph>CFbsBitmap::LockHeap()</codeph> and <codeph>CFbsBitmap::UnlockHeap()</codeph> with
-calls to the new functions <codeph>CFbsBitmap::BeginDataAccess()</codeph> and <codeph>CFbsBitmap::EndDataAccess()</codeph>.
-If necessary also add a mutual exclusion object to multi-threaded applications.
-Although not strictly necessary, calling <codeph>CFbsBitmap::BeginDataAccess()</codeph> and <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita#GUID-683A1D42-2764-3EB7-BD19-9E12559199AB/GUID-0C2D1B5F-46A8-32A1-9558-24BC8A413258"><apiname>CFbsBitmap::EndDataAccess()</apiname></xref> ensures
-optimum performance in platforms with graphics hardware acceleration. </p> <p>For
-the benefit of legacy applications that do not require changes, <codeph>CFbsBitmap::LockHeap()</codeph> and <codeph>CFbsBitmap::UnlockHeap()</codeph> now simply call <codeph>CFbsBitmap::BeginDataAccess()</codeph> and <codeph>CFbsBitmap::EndDataAccess()</codeph>,
-respectively. </p> <p>Any number of client threads can now call <codeph>CFbsBitmap::DataAddress()</codeph> and
-manipulate bitmap data at the same time. This does not cause a problem provided
-each client thread accesses a different bitmap. If a multi-threaded application
-shares a bitmap among several threads and assumes that <codeph>CFbsBitmap::LockHeap()</codeph> is
-implemented as a <codeph>Wait()</codeph> operation on a mutual exclusion object,
-you may need to modify the application. </p> <p><b>The impact of the change
-on existing applications </b> </p> <p>The old documentation was ambiguous
-about several aspects of the semantics of the heap locking API. However, because
-the actual implementation used a global mutual exclusion object, it was possible
-for a client thread to call <codeph>CFbsBitmap::LockHeap()</codeph> and prevent
-any other client thread that called <codeph>CFbsBitmap::LockHeap()</codeph> from
-proceeding. This included client threads that attempted to access the same
-bitmap and totally unrelated client threads. Therefore, the heap locking API
-may have been used as a synchronisation mechanism in multi-threaded applications.
-This is no longer possible. </p> <p>The <xref href="GUID-B18430C6-0FC1-3EE6-AC5C-A30B6AE88217.dita"><apiname>SYMBIAN_DEBUG_FBS_LOCKHEAP</apiname></xref> macro
-can be used to help detect multi-threaded applications that share a bitmap
-among several threads and fail to provide their own mutual exclusion mechanism.
-When this macro is defined in debug builds of the Font and Bitmap Server, <codeph>CFbsBitmap::LockHeap()</codeph> and <codeph>CFbsBitmap::UnlockHeap()</codeph> check whether more than one client thread has a call to <codeph>CFbsBitmap::LockHeap()</codeph> on
-the same bitmap at the same time without a corresponding call to <codeph>CFbsBitmap::UnlockHeap()</codeph>.
-When this is detected, a panic FBSCLI 22 is raised. </p> <p>The impact of
-the change on existing multi-threaded applications that use the heap locking
-API as a synchronisation mechanism is reduced, in most of the cases, to the
-possibility of loss of bitmap data changes rather than illegal memory access
-or any other kind of abnormal termination. An exception is the case of existing
-multi-threaded applications that use the heap locking API as a synchronisation
-mechanism where one thread calls <codeph>CFbsBitmap::Resize()</codeph> on
-a bitmap while another thread calls <codeph>CFbsBitmap::SizeInPixels()</codeph> followed
-by <codeph>CFbsBitmap::DataAddress()</codeph> on the same bitmap. This can
-produce an incorrect value for the size in pixels and lead to an illegal memory
-access. </p> </section>
-</conbody><related-links>
-<link href="GUID-71DADA82-3ABC-52D2-8360-33FAEB2E5DE9.dita"><linktext>Font and
-Bitmap Server Overview</linktext></link>
-<link href="GUID-90644B52-69D7-595C-95E3-D6F7A30C060D.dita"><linktext>Font and
-Text Services Collection Overview </linktext></link>
+<?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-30CAE438-6CC7-5532-8727-781B8E83574A" xml:lang="en"><title>Heap
+Locking in the Font and Bitmap Server </title><shortdesc>The Font and Bitmap Server's heap locking API is deprecated in
+Symbian OS v9.3 and later versions. This topic explains the rationale for
+this and how it affects existing applications that use the <codeph>CFBsBitmap::LockHeap()</codeph>, <codeph>CFBsBitmap::LockHeapLC()</codeph> and <codeph>CFbsBitmap::UnlockHeap()</codeph> functions. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
+<section><title>Heap locking in previous versions </title> <p>Prior to Symbian
+OS v9.3, the Font and Bitmap Server made a distinction between small bitmaps
+and large bitmaps. The data for large bitmaps was stored in a separate global
+memory heap where a de-fragmentation algorithm was used. When necessary, this
+algorithm moved bitmap data in the virtual address space. As a result it was
+possible for an application to allocate a new bitmap and trigger the de-fragmentation
+algorithm while an unrelated application accessed the data of another bitmap.
+From an application's point of view, this meant that the value returned by <codeph>CFbsBitmap::DataAddress()</codeph> could
+change unpredictably at any time. </p> <p>The solution was to lock the global
+memory heap by calling <codeph>CFbsBitmap::LockHeap()</codeph> or <codeph>CFbsBitmap::LockHeapLC()</codeph> before
+calling <codeph>CFbsBitmap::DataAddress()</codeph>. When the application finished
+accessing the bitmap data, it unlocked the global memory heap by calling <codeph>CFbsBitmap::UnlockHeap().</codeph> Internally
+the Font and Bitmap Server used a global mutual exclusion object to implement
+the heap locking functions and waited on it before performing any operation
+that could trigger the de-fragmentation algorithm. </p> <p>Although it was
+undocumented functionality, multi-threaded applications could use the heap
+locking functions as a way of synchronizing access to bitmaps shared among
+several threads, because calls to <codeph>CFbsBitmap::LockHeap()</codeph> and <codeph>CFbsBitmap::UnlockHeap()</codeph> translated
+into <codeph>Wait()</codeph> and <codeph>Signal()</codeph> operations on the
+global mutual exclusion object. </p> </section>
+<section><title>Removal of heap locking </title> <p><b>Use of a disconnected
+memory chunk </b> </p> <p>From Symbian OS v9.3, all bitmap data is kept in
+a disconnected global memory chunk. This is a new type of chunk that does
+not require the set of pages committed to physical memory to form a contiguous
+block in the virtual address space. A virtual address range much bigger than
+the amount of physical memory is reserved, and pages are committed to physical
+memory when allocating bitmaps and de-committed when freeing them. </p> <p>As
+a result, fragmentation in the reserved virtual address range is not a problem
+and fragmentation in the physical address space is handled transparently by
+the Memory Management Unit (MMU). Therefore, de-fragmentation is not necessary
+and bitmap operations do not need to move data belonging to other bitmaps. </p> <p><b>Removal
+of in-place operations </b> </p> <p>Some bitmap operations, such as <codeph>CFbsBitmap::Resize()</codeph>, <codeph>CFbsBitmap::Compress()</codeph> and <codeph>CFbsBitmap::CompressInBackground()</codeph>, can change the
+value returned by <codeph>CFbsBitmap::DataAddress()</codeph> because they
+may need to re-allocate memory. These functions have a new implementation.
+They now create a new bitmap object inside the Font and Bitmap Server and
+update the reference contained in the <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> object.
+The old bitmap is destroyed immediately if it is referenced only by the <codeph>CFbsBitmap</codeph> object
+on which the re-allocating function was called. Otherwise, the old bitmap
+is flagged as <b>dirty</b> and its destruction is deferred until its reference
+count becomes zero. </p> <p>All of the functions in the <codeph>CFbsBitmap</codeph> class
+now check whether the referenced bitmap is dirty before proceeding. If it
+is, the Font and Bitmap Server updates the reference to point to the new bitmap.
+When all of the <codeph>CFbsBitmap</codeph> objects that referenced the old
+bitmap have had their references updated or have been deleted, the reference
+count of the old bitmap becomes zero and it is destroyed. </p> <p>The impact
+on performance of this change is negligible, because the dirty flag is tested
+in the context of the client thread and in most cases bitmaps are "clean". </p> <p>Sometimes
+multiple <codeph>CFbsBitmap</codeph> objects in different client threads reference
+the same bitmap. When a client thread calls a re-allocating function on a
+bitmap while another client thread is accessing the bitmap data through a
+pointer returned by <codeph>CFbsBitmap::DataAddress()</codeph>, there is no
+illegal memory access because the old bitmap still exists. This scenario typically
+occurs when an application calls <codeph>CFbsBitmap::CompressInBackground()</codeph> on
+a bitmap and continues to use it, because the compression is performed asynchronously
+at an unspecified time. </p> <p><b>Deprecation of the heap locking functions </b> </p> <p>The
+use of a disconnected memory chunk and the removal of in-place operations
+allow the Font and Bitmap Server to work without heap locking. Therefore, <codeph>CFbsBitmap::LockHeap()</codeph>, <codeph>CFbsBitmap::UnlockHeap()</codeph> and <codeph>CFbsBitmap::LockHeapLC()</codeph> are no longer necessary and
+have been deprecated.<b> These functions no longer provide any locking functionality
+and cannot be used as a synchronization mechanism</b>. </p> <p>It is recommended
+that you replace all calls to <codeph>CFbsBitmap::LockHeap()</codeph> and <codeph>CFbsBitmap::UnlockHeap()</codeph> with
+calls to the new functions <codeph>CFbsBitmap::BeginDataAccess()</codeph> and <codeph>CFbsBitmap::EndDataAccess()</codeph>.
+If necessary also add a mutual exclusion object to multi-threaded applications.
+Although not strictly necessary, calling <codeph>CFbsBitmap::BeginDataAccess()</codeph> and <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita#GUID-683A1D42-2764-3EB7-BD19-9E12559199AB/GUID-0C2D1B5F-46A8-32A1-9558-24BC8A413258"><apiname>CFbsBitmap::EndDataAccess()</apiname></xref> ensures
+optimum performance in platforms with graphics hardware acceleration. </p> <p>For
+the benefit of legacy applications that do not require changes, <codeph>CFbsBitmap::LockHeap()</codeph> and <codeph>CFbsBitmap::UnlockHeap()</codeph> now simply call <codeph>CFbsBitmap::BeginDataAccess()</codeph> and <codeph>CFbsBitmap::EndDataAccess()</codeph>,
+respectively. </p> <p>Any number of client threads can now call <codeph>CFbsBitmap::DataAddress()</codeph> and
+manipulate bitmap data at the same time. This does not cause a problem provided
+each client thread accesses a different bitmap. If a multi-threaded application
+shares a bitmap among several threads and assumes that <codeph>CFbsBitmap::LockHeap()</codeph> is
+implemented as a <codeph>Wait()</codeph> operation on a mutual exclusion object,
+you may need to modify the application. </p> <p><b>The impact of the change
+on existing applications </b> </p> <p>The old documentation was ambiguous
+about several aspects of the semantics of the heap locking API. However, because
+the actual implementation used a global mutual exclusion object, it was possible
+for a client thread to call <codeph>CFbsBitmap::LockHeap()</codeph> and prevent
+any other client thread that called <codeph>CFbsBitmap::LockHeap()</codeph> from
+proceeding. This included client threads that attempted to access the same
+bitmap and totally unrelated client threads. Therefore, the heap locking API
+may have been used as a synchronisation mechanism in multi-threaded applications.
+This is no longer possible. </p> <p>The <xref href="GUID-B18430C6-0FC1-3EE6-AC5C-A30B6AE88217.dita"><apiname>SYMBIAN_DEBUG_FBS_LOCKHEAP</apiname></xref> macro
+can be used to help detect multi-threaded applications that share a bitmap
+among several threads and fail to provide their own mutual exclusion mechanism.
+When this macro is defined in debug builds of the Font and Bitmap Server, <codeph>CFbsBitmap::LockHeap()</codeph> and <codeph>CFbsBitmap::UnlockHeap()</codeph> check whether more than one client thread has a call to <codeph>CFbsBitmap::LockHeap()</codeph> on
+the same bitmap at the same time without a corresponding call to <codeph>CFbsBitmap::UnlockHeap()</codeph>.
+When this is detected, a panic FBSCLI 22 is raised. </p> <p>The impact of
+the change on existing multi-threaded applications that use the heap locking
+API as a synchronisation mechanism is reduced, in most of the cases, to the
+possibility of loss of bitmap data changes rather than illegal memory access
+or any other kind of abnormal termination. An exception is the case of existing
+multi-threaded applications that use the heap locking API as a synchronisation
+mechanism where one thread calls <codeph>CFbsBitmap::Resize()</codeph> on
+a bitmap while another thread calls <codeph>CFbsBitmap::SizeInPixels()</codeph> followed
+by <codeph>CFbsBitmap::DataAddress()</codeph> on the same bitmap. This can
+produce an incorrect value for the size in pixels and lead to an illegal memory
+access. </p> </section>
+</conbody><related-links>
+<link href="GUID-71DADA82-3ABC-52D2-8360-33FAEB2E5DE9.dita"><linktext>Font and
+Bitmap Server Overview</linktext></link>
+<link href="GUID-90644B52-69D7-595C-95E3-D6F7A30C060D.dita"><linktext>Font and
+Text Services Collection Overview </linktext></link>
</related-links></concept>
\ No newline at end of file