<?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>