/*
* Copyright (c) 2006 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:
*
* Description:
*
*/
#ifndef _MEMORYMANAGER_H_
#define _MEMORYMANAGER_H_
// INCLUDES
#include <e32std.h>
#include <e32base.h>
// CONSTANTS
// MACROS
//
// DATA TYPES
enum TOOMCheckResult
{
ENoOOM = 0x0000, // no oom
ECheckOOM = 0x0001, // last memory check failed
EUserAllocOOM = 0x0002, // system heap allocation failed
ERescueOOM = 0x0004, // rescue buffer allocation failed
ECollecting = 0x0010, // memory manager is collecting memory
EStopping = 0x0020 // memory menager is stopping operations
};
// simulate OOM, for debugging purpose
enum TOOMType
{
EOOM_None = 0x0000,
EOOM_Heap1 = 0x0001, // fail the first heap allocation
EOOM_Heap2 = 0x0003, // fail the second heap allocation, after collection
EOOM_Rescue = 0x0007 // fail the rescue allocation
};
enum TOOMPriority
{
EOOM_PriorityLow = 0,
EOOM_PriorityMiddle,
EOOM_PriorityHigh,
EOOM_PriorityCritical
};
// FUNCTION PROTOTYPES
// FORWARD DECLARATIONS
class CAllocator;
class FunctionLogger;
// CLASS DECLARATION
/**
*
* @lib memman.lib
* @since 3.1
*/
class MMemoryCollector
{
public: // New functions
/**
* Collect free memory, this function is called when allocation from
* System heap fails
* @since 3.1
* @param amount of memory needs to be collected
* @return amount of memory collected
*/
virtual TUint Collect(TUint aRequired) = 0;
/**
* restore the entity controlled memory collector when there is enough memory
* System heap fails
* @since 3.1
* @param
* @return
*/
virtual void Restore() = 0;
/**
* Priority of this collector, 0 - lowest, 10 - highest;
* the lower the priority, the earlier this collector is executed.
* @since 3.1
* @param
* @return
*/
virtual TOOMPriority Priority() = 0;
};
/**
*
* @lib memman.lib
* @since 3.1
*/
class MOOMStopper
{
public: // New functions
/**
* Stop currently on-going operations, called by the allocator
* @since 3.1
* @param
* @return
*/
virtual void Stop() = 0;
/**
* return the priority of this stopper (1-100), allocator expects this value
* to determine the stopping order. The higher the priority is, the sooner
* this stopper will be called.
* @since 3.1
* @param
* @return
*/
virtual TOOMPriority Priority() = 0;
};
/**
*
* @lib memman.lib
* @since 3.1
*/
class MOOMNotifier
{
public: // New functions
/**
* client provided notifying utility function, called by the allocator
* to inform the user
* @since 3.1
* @param
* @return
*/
virtual TInt Notify() = 0;
};
/**
* A class handles all memory operations and OOM issues
* @lib memman.lib
* @since 3.1
*/
class MemoryManager
{
public:
/**
* register a memory collector, memory manager doesn't own this collector
* @since 3.1
* @param aCollector the collector to be registered
* @param
* @return
*/
IMPORT_C static void AddCollector( MMemoryCollector* aCollector );
/**
* unregister a memory collector
* @since 3.1
* @param aCollector the collector to be unregistered
* @param
* @return
*/
IMPORT_C static void RemoveCollector( MMemoryCollector* aCollector );
/**
* register a stopper, memory manager doesn't own this stopper.
* @since 3.1
* @param aStopper the stopper to be registered
* @param
* @return
*/
IMPORT_C static void AddStopper( MOOMStopper* aStopper );
/**
* unregister a stopper
* @since 3.1
* @param aStopper the stopper to be unregistered
* @param
* @return
*/
IMPORT_C static void RemoveStopper( MOOMStopper* aStopper );
/**
* set the OOM notifier, memory manager doesn't own this notifier
* @since 3.1
* @param aNotifier the notifier
* @param
* @return
*/
IMPORT_C static void SetNotifier( MOOMNotifier* aNotifier );
/**
* check if the memory manager is able to reserve enough memory for the coming operation.
* @since 3.1
* @param aTotalSize total amount of memory
* @param aMaxBufSizse the biggest contiguous memory buffer
* @param aChecker the name of operation
* @return result of prechecking, ETrue = successful
*/
IMPORT_C static TBool PreCheck( TUint aTotalSize, TUint aMaxBufSize, const TDesC8& aChecker=KNullDesC8 );
/**
* An additional check after an operation is completed.
* @since 3.1
* @param
* @param
* @return the status of memory during this operation.
*/
IMPORT_C static TUint PostCheck();
/**
* Get the status of memory manager, specific state could be retrieve by AND (&) operator
* with TOOMCheckResult enum
* @since 3.1
* @param
* @param
* @return the status of memory during this operation.
*/
IMPORT_C static TUint Status();
/**
* Trigger an OOM event, this function is only for debugging purpose
* @since 3.1
* @param aType defines where memory allocation fails
* @param
* @return
*/
IMPORT_C static void SetStatus( TOOMCheckResult aType = ENoOOM );
/**
* Prepare Memory manager for the coming application exit.
* @since 3.1
* @param
* @param
* @return
*/
IMPORT_C static void PrepareForExit();
/**
* Free some RAM. Calls collect on registered collectors
* @since 3.1
* @param
* @param
* @return
*/
IMPORT_C static void FreeRam();
/**
* Called when application is no longer in OOM situation.
* @since 3.1
* @param
* @param
* @return
*/
IMPORT_C static void RestoreCollectors();
/**
* Called when application wants to change the rescue buffer size
* @since 3.1
* @param
* @param
* @return
*/
IMPORT_C static void SetRescueBufferSize(TInt aSize);
/**
* retrieve the size of an allocated memory cell
* @since 3.1
* @param
* @param
* @return
*/
IMPORT_C static TUint MemorySize(TAny* aPtr);
/**
* switch to the allocator using fast dlmalloc
* @since 3.1
* @param
* @param
* @return
*/
IMPORT_C static RAllocator* SwitchToFastAllocator();
/**
* switch to the default allocator provided by Symbian OS,
* and close the current fast allocator.
* @since 3.1
* @param
* @param
* @return
*/
IMPORT_C static void CloseFastAllocator(RAllocator* aDefaultAllocator);
/**
* Create fast allocator and switch as default heap. Special case if fast allocator
* has to be created from SetupThreadHeap().
*
* @since 9.2
* @param
* @return
*/
IMPORT_C static void CreateFastAllocator();
/**
* Initialize MemoryManager library. Special case if CreateFastAllocator is
* called from SetupThreadHeap().
*
* @since 9.2
* @param
* @return
*/
IMPORT_C static void InitFastAllocator();
/**
* initialize the OOM handler in the memorypool
* @since 9.2
* @param
* @param
* @return
*/
IMPORT_C static void InitOOMDialog();
/**
* Reset the OOM dialog display flag in the memorypool; we want to pop the OOM dialog once per page,
* so we need to clear this when we are either done with the page (it unloads) or when we load a new one,
* so that it will display again when we run out of memory
* @since 9.2
* @param
* @param
* @return
*/
IMPORT_C static void ResetOOMDialogDisplayed();
/**
* Dumps the memory logs i.e. heap allocated, heap free, system free, heap size etc to log
* file c:\logs\webcore\Memory.log
* @since 9.2
* @param
* @return
*/
IMPORT_C static void DumpMemoryLogs();
};
#endif// !_MEMORYMANAGER_H_