--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-30CAE438-6CC7-5532-8727-781B8E83574A.dita	Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +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>
+</related-links></concept>
\ No newline at end of file