--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-E3A80D62-09A5-502D-AB55-6AB2A5623465.dita	Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,53 @@
+<?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 task
+  PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
+<task id="GUID-E3A80D62-09A5-502D-AB55-6AB2A5623465" xml:lang="en"><title>Cleaning-up
+Memory</title><shortdesc>To ensure the plug-in framework unloads the plug-in DLLs when they
+are no longer required and releases associated memory, the clients should
+follow an explicit memory cleanup procedure. The main purpose is to release
+memory and close handles held on unused plug-in implementations and their
+associated DLLs. The memory clean-up should be performed after all instantiated
+interface objects have been deleted. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody>
+<context><p>The plug-in framework client-side library implements a deferred
+cleanup mechanism in the client process to handle destroyed plug-ins. Following
+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
+destructor, the plug-in’s reference count is decremented to zero and the client-side
+library has a “last destroyed last plug-in” garbage pointer. The internal
+framework memory associated with the garbage plug-in is released. The handles
+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>.
+This chain of deferred cleanup in the client thread requires the final plug-in
+in the garbage queue to be released. Hence there is a requirement for explicit
+memory clean-up. The memory clean-up is performed by the clients of the plug-in
+framework. <note> The destructor of the interface implementation deletes the
+instantiated objects obtained from an interface when they are no longer required
+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()
+    {
+    REComSession::DestroyedImplementation(iDtor_ID_Key);
+    }</codeblock></note></p> </context>
+<steps id="GUID-31FD83CA-3EC3-5EA2-8297-21165CC16335">
+<step id="GUID-BB4A525E-4D43-59F0-8D45-136D31258FDA"><cmd/>
+<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
+to ensure the plug-in framework executes the final cleanup steps. </info>
+<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
+called from a plug-in implementation class destructor, especially following
+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
+that the plug-in's supporting DLL may immediately be unloaded by the Kernel
+due to the closure of RLibrary handles. It can result in a KERN-EXEC if the
+destructor call stack is still inside the DLL that is unloaded. </info>
+</step>
+<step id="GUID-AA4796C3-0F56-5AE2-A278-08CA615C4157"><cmd/>
+<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
+be invoked within the library's shutdown function. This makes the library's
+use of plug-in framework transparent to the clients. </info>
+<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>
+</step>
+</steps>
+</taskbody></task>
\ No newline at end of file