/*

* 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

        */        

        /**

        * Initialize MemoryManager library. Special case if CreateFastAllocator is

        * called from SetupThreadHeap().

        * 

        * @since 9.2

        * @param

        * @return

        */

        /**

        * 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();

    };

#endif// !_MEMORYMANAGER_H_