1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE task

    11   PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

    12 <task id="GUID-E3A80D62-09A5-502D-AB55-6AB2A5623465" xml:lang="en"><title>Cleaning-up

    13 Memory</title><shortdesc>To ensure the plug-in framework unloads the plug-in DLLs when they

    14 are no longer required and releases associated memory, the clients should

    15 follow an explicit memory cleanup procedure. The main purpose is to release

    16 memory and close handles held on unused plug-in implementations and their

    17 associated DLLs. The memory clean-up should be performed after all instantiated

    18 interface objects have been deleted. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody>

    19 <context><p>The plug-in framework client-side library implements a deferred

    20 cleanup mechanism in the client process to handle destroyed plug-ins. Following

    21 a call to <xref href="GUID-1344F049-81C4-3D17-AF46-8B5584680ADB.dita#GUID-1344F049-81C4-3D17-AF46-8B5584680ADB/GUID-8BA69111-0451-34CA-A1E8-C83513C4D29D"><apiname>REComSession::DestroyedImplementation()</apiname></xref> in the

    22 destructor, the plug-in’s reference count is decremented to zero and the client-side

    23 library has a “last destroyed last plug-in” garbage pointer. The internal

    24 framework memory associated with the garbage plug-in is released. The handles

    25 on the DLL are closed at the beginning of the next call to <xref href="GUID-1344F049-81C4-3D17-AF46-8B5584680ADB.dita#GUID-1344F049-81C4-3D17-AF46-8B5584680ADB/GUID-8BA69111-0451-34CA-A1E8-C83513C4D29D"><apiname>REComSession::DestroyedImplementation()</apiname></xref>.

    26 This chain of deferred cleanup in the client thread requires the final plug-in

    27 in the garbage queue to be released. Hence there is a requirement for explicit

    28 memory clean-up. The memory clean-up is performed by the clients of the plug-in

    29 framework. <note> The destructor of the interface implementation deletes the

    30 instantiated objects obtained from an interface when they are no longer required

    31 by calling the static function <xref href="GUID-1344F049-81C4-3D17-AF46-8B5584680ADB.dita#GUID-1344F049-81C4-3D17-AF46-8B5584680ADB/GUID-8BA69111-0451-34CA-A1E8-C83513C4D29D"><apiname>REComSession::DestroyedImplementation()</apiname></xref>. <codeblock xml:space="preserve">inline CExampleInterfaceDefinition::~CExampleInterfaceDefinition()

    32     {

    33     REComSession::DestroyedImplementation(iDtor_ID_Key);

    34     }</codeblock></note></p> </context>

    35 <steps id="GUID-31FD83CA-3EC3-5EA2-8297-21165CC16335">

    36 <step id="GUID-BB4A525E-4D43-59F0-8D45-136D31258FDA"><cmd/>

    37 <info>Call <xref href="GUID-1344F049-81C4-3D17-AF46-8B5584680ADB.dita#GUID-1344F049-81C4-3D17-AF46-8B5584680ADB/GUID-1AACEF53-2CAD-34EC-A485-CE49BC8B9BD8"><apiname>REComSession::FinalClose()</apiname></xref> before shut down

    38 to ensure the plug-in framework executes the final cleanup steps. </info>

    39 <info> Note:  <xref href="GUID-1344F049-81C4-3D17-AF46-8B5584680ADB.dita#GUID-1344F049-81C4-3D17-AF46-8B5584680ADB/GUID-1AACEF53-2CAD-34EC-A485-CE49BC8B9BD8"><apiname>REComSession::FinalClose()</apiname></xref> should not be

    40 called from a plug-in implementation class destructor, especially following

    41 a <xref href="GUID-1344F049-81C4-3D17-AF46-8B5584680ADB.dita#GUID-1344F049-81C4-3D17-AF46-8B5584680ADB/GUID-8BA69111-0451-34CA-A1E8-C83513C4D29D"><apiname>REComSession::DestroyedImplementation()</apiname></xref>. There is a risk

    42 that the plug-in's supporting DLL may immediately be unloaded by the Kernel

    43 due to the closure of RLibrary handles. It can result in a KERN-EXEC if the

    44 destructor call stack is still inside the DLL that is unloaded. </info>

    45 </step>

    46 <step id="GUID-AA4796C3-0F56-5AE2-A278-08CA615C4157"><cmd/>

    47 <info>If the plug-in framework is used in a library, then <xref href="GUID-1344F049-81C4-3D17-AF46-8B5584680ADB.dita#GUID-1344F049-81C4-3D17-AF46-8B5584680ADB/GUID-1AACEF53-2CAD-34EC-A485-CE49BC8B9BD8"><apiname>REComSession::FinalClose()</apiname></xref> should

    48 be invoked within the library's shutdown function. This makes the library's

    49 use of plug-in framework transparent to the clients. </info>

    50 <info>It is not an error if both the library and client call <xref href="GUID-1344F049-81C4-3D17-AF46-8B5584680ADB.dita#GUID-1344F049-81C4-3D17-AF46-8B5584680ADB/GUID-1AACEF53-2CAD-34EC-A485-CE49BC8B9BD8"><apiname>REComSession::FinalClose()</apiname></xref>. </info>

    51 </step>

    52 </steps>

    53 </taskbody></task>