williamr@2: // Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: // All rights reserved.
williamr@2: // This component and the accompanying materials are made available
williamr@4: // under the terms of "Eclipse Public License v1.0"
williamr@2: // which accompanies this distribution, and is available
williamr@4: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2: //
williamr@2: // Initial Contributors:
williamr@2: // Nokia Corporation - initial contribution.
williamr@2: //
williamr@2: // Contributors:
williamr@2: //
williamr@2: // Description:
williamr@2: //
williamr@2: 
williamr@2: #if !defined(__S32PAGE_H__)
williamr@2: #define __S32PAGE_H__
williamr@2: #if !defined(__S32STRM_H__)
williamr@2: #include <s32strm.h>
williamr@2: #endif
williamr@2: 
williamr@2: /** Size of the pages in the page pool. */
williamr@2: const TInt KPoolPageSize=512;
williamr@2: //
williamr@2: const TUint32 KNullPageRefValue=0;
williamr@2: 
williamr@2: /**
williamr@2:  * @publishedAll 
williamr@2:  * @released
williamr@2:  * Encapsulates a page reference.
williamr@2: 
williamr@2: A page reference is an integer value that can be used to identify a page. 
williamr@2:  */
williamr@2: class TPageRef
williamr@2: 	{
williamr@2: public:
williamr@2: 	/** Default constructor. */
williamr@2: 	inline TPageRef() {}
williamr@2: 	inline TPageRef(TUint32 aValue);
williamr@2: //
williamr@2: 	inline TBool operator==(TPageRef aRef) const;
williamr@2: 	inline TBool operator!=(TPageRef aRef) const;
williamr@2: //
williamr@2: 	inline void ExternalizeL(RWriteStream& aStream) const;
williamr@2: 	inline void InternalizeL(RReadStream& aStream);
williamr@2: //
williamr@2: 	inline TUint32 Value() const;
williamr@2: private:
williamr@2: 	TUint32 iVal;
williamr@2: 	};
williamr@2: #if defined(__NO_CLASS_CONSTS__)
williamr@2: #define KNullPageRef TPageRef(KNullPageRefValue)
williamr@2: #else
williamr@2: /** Defines a null page reference. */
williamr@2: const TPageRef KNullPageRef=TPageRef(KNullPageRefValue);
williamr@2: #endif
williamr@2: 
williamr@2: class MPagePool;
williamr@2: /** Typedef to define a function that abandons pages in page pool. It is used by 
williamr@2: MPagePool::AcquireL().
williamr@2: 
williamr@2: @see MPagePool::AcquireL() */
williamr@2: typedef void (*TPageAbandonFunction)(MPagePool& aPool);
williamr@2: 
williamr@2: /** Flags that define how allocated pages can be reclaimed.
williamr@2: 
williamr@2: A BTree can locate some pages even when the tree is broken, but not all. The 
williamr@2: ones it cannot track must be tracked by the page pool in order to reclaim 
williamr@2: the storage if the tree breaks. */
williamr@2: enum TPageReclamation 
williamr@2: 	/** The page can be deleted, but its space not reclaimed.
williamr@2: 	
williamr@2: 	The page pool will not track these pages, so to retrieve the space the page 
williamr@2: 	must be deleted explicitly. */
williamr@2: 	{EPageDeleteOnly,
williamr@2: 	/** Page can be reclaimed.
williamr@2: 	
williamr@2: 	The page pool will track these pages, and will be able to reclaim the pages 
williamr@2: 	when, for example, RStorePagePool::ReclaimL() is called. */
williamr@2: 	EPageReclaimable};
williamr@2: 
williamr@2: /** Flags that define how a page should be treated when it is unlocked. */
williamr@2: enum TPageChange 
williamr@2: 	/** Unlock only. */
williamr@2: 	{EPageNoChange,
williamr@2: 	/** Mark the page as dirty. */
williamr@2: 	EPageDirty,
williamr@2: 	/** Mark the page as needing a safe update. */
williamr@2: 	EPageUpdate,
williamr@2: 	/** Discard the page. */
williamr@2: 	EPageAbandon=-1};
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2:  * @publishedAll 
williamr@2:  * @released
williamr@2:  * Interface to a page pool, the storage abstraction used by the B-trees API. 
williamr@2: 
williamr@2: The interface is abstract and handles pages as TAny pointers. It is left to 
williamr@2: derived classes to implement page storage in a particular storage medium, 
williamr@2: such as memory or disk.  
williamr@2: */
williamr@2: class MPagePool
williamr@2: 	{
williamr@2: public:
williamr@2: 	IMPORT_C void PushL();
williamr@2: 	inline void Pop();
williamr@2: 
williamr@2: 	/** Returns a function that abandons all locked pages for this page pool. 
williamr@2: 	
williamr@2: 	@return A function that abandons all locked pages for this page pool. */
williamr@2: 	virtual TPageAbandonFunction AcquireL()=0;
williamr@2: //
williamr@2: 	virtual TAny* AllocL()=0;
williamr@2: 
williamr@2: 	/** Locks a page and returns a pointer to it.
williamr@2: 	
williamr@2: 	@param aRef Reference to the page to lock
williamr@2: 	@return Locked page */
williamr@2: 	virtual TAny* LockL(TPageRef aRef)=0;
williamr@2: //
williamr@2: 	virtual TPageRef AssignL(const TAny* aPage,TPageReclamation aReclamation=EPageDeleteOnly)=0;
williamr@2: 
williamr@2: 	/** Updates a page. 
williamr@2: 	
williamr@2: 	This can be used for cached pages that may have become outdated.
williamr@2: 	
williamr@2: 	@param aPage Page to update */
williamr@2: 	virtual void UpdateL(const TAny* aPage)=0;
williamr@2: 
williamr@2: 	/** Unlocks a page.
williamr@2: 	
williamr@2: 	@param aPage Page to unlock
williamr@2: 	@param aChange How the page should be treated once it is unlocked */
williamr@2: 	virtual void Unlock(const TAny* aPage,TPageChange aChange=EPageNoChange)=0;
williamr@2: //
williamr@2: 	IMPORT_C void Delete(TPageRef aRef);
williamr@2: 	IMPORT_C void DeleteL(TPageRef aRef);
williamr@2: protected:
williamr@2: 	virtual void DoDeleteL(TPageRef aRef)=0;
williamr@2: 	};
williamr@2: 
williamr@2: /**
williamr@2:  * @publishedAll 
williamr@2:  * @released
williamr@2:  * Uses memory to implement the MPagePool page pool interface.
williamr@2: 
williamr@2: The class allocates pages from the default heap, storing them in an array. 
williamr@2: This pool is not persistent.
williamr@2:  */
williamr@2: class CMemPagePool : public CBase,public MPagePool
williamr@2: 	{
williamr@2: public:
williamr@2: 	IMPORT_C static CMemPagePool* NewL();
williamr@2: 	IMPORT_C static CMemPagePool* NewLC();
williamr@2: 	IMPORT_C CMemPagePool();
williamr@2: 	IMPORT_C ~CMemPagePool();
williamr@2: //
williamr@2: 	IMPORT_C TPageAbandonFunction AcquireL();
williamr@2: 	IMPORT_C TAny* AllocL();
williamr@2: 	IMPORT_C TAny* LockL(TPageRef aRef);
williamr@2: 	IMPORT_C TPageRef AssignL(const TAny* aPage,TPageReclamation aReclamation=EPageDeleteOnly);
williamr@2: 	IMPORT_C void UpdateL(const TAny* aPage);
williamr@2: 	IMPORT_C void Unlock(const TAny* aPage,TPageChange aChange=EPageNoChange);
williamr@2: protected:
williamr@2: 	IMPORT_C void DoDeleteL(TPageRef aRef);
williamr@2: private:
williamr@2: 	TAny*& PageL(TPageRef aRef);
williamr@2: 	static void DoAbandon(MPagePool& aPool);
williamr@2: private:
williamr@2: 	CArrayFixSeg<TAny*> iPages;
williamr@2: 	};
williamr@2: //
williamr@2: #if defined(_DEBUG)&&!defined(__PAGE_CACHE_STATS)
williamr@2: //#define __PAGE_CACHE_STATS
williamr@2: #endif
williamr@2: //
williamr@2: class TCachePage;
williamr@2: struct SCachePage;
williamr@2: class TCachePagePool;
williamr@2: 
williamr@2: /**
williamr@2:  * @publishedAll 
williamr@2:  * @released
williamr@2:  * Provides a cache for page pools. 
williamr@2: 
williamr@2: Persistent page pools rely on a cache to provide in-memory space for their 
williamr@2: pages and to cache frequently accessed pages.  
williamr@2: */
williamr@2: class CPageCache : public CBase
williamr@2: 	{
williamr@2: public:
williamr@2: 	enum {EDefaultPages=20};
williamr@2: #if defined(__PAGE_CACHE_STATS)
williamr@2: 	
williamr@2: 	/**
williamr@2: 	 * @publishedAll 
williamr@2: 	 * @released
williamr@2: 	 */
williamr@2: 	class TStats
williamr@2: 		{
williamr@2: 	public:
williamr@2: 		inline TInt Requests() const;
williamr@2: 		inline TInt Hits() const;
williamr@2: 		inline TInt Misses() const;
williamr@2: 		inline void Reset();
williamr@2: 	private:
williamr@2: 		inline void Hit();
williamr@2: 		inline void Miss();
williamr@2: 	private:
williamr@2: 		TInt iRequests;
williamr@2: 		TInt iMisses;
williamr@2: 	private:
williamr@2: 		friend class CPageCache;
williamr@2: 		};
williamr@2: #endif
williamr@2: public:
williamr@2: 	IMPORT_C static CPageCache* NewL(TInt aPages=EDefaultPages);
williamr@2: 	IMPORT_C static CPageCache* NewLC(TInt aPages=EDefaultPages);
williamr@2: 	IMPORT_C CPageCache();
williamr@2: 	IMPORT_C void ConstructL(TInt aPages=EDefaultPages);
williamr@2: 	IMPORT_C ~CPageCache();
williamr@2: //
williamr@2: #if defined(__PAGE_CACHE_STATS)
williamr@2: 	inline TStats& Stats();
williamr@2: 	inline const TStats& Stats() const;
williamr@2: #endif
williamr@2: private:
williamr@2: 	TCachePage* Find(TCachePagePool* aPool,TPageRef aRef);
williamr@2: private:
williamr@2: 	SCachePage* iPages;
williamr@2: 	SCachePage* iEnd;
williamr@2: 	TDblQue<TCachePage> iFree;
williamr@2: #if defined(__PAGE_CACHE_STATS)
williamr@2: 	TStats iStats;
williamr@2: #endif
williamr@2: private:
williamr@2: 	friend class TCachePagePool;
williamr@2: 	};
williamr@2: 
williamr@2: /**
williamr@2:  * @publishedAll 
williamr@2:  * @released
williamr@2:  * Provides a page pool with cached pages.
williamr@2: 
williamr@2: It is an intermediary class, used in the definition of page pools that use 
williamr@2: a cache, such as RFilePagePool and RStorePagePool.
williamr@2: 
williamr@2: @see RFilePagePool
williamr@2: @see RStorePagePool  
williamr@2: */
williamr@2: class TCachePagePool : public MPagePool
williamr@2: 	{
williamr@2: public:
williamr@2: 	inline void Set(CPageCache& aCache);
williamr@2: //
williamr@2: 	IMPORT_C TPageAbandonFunction AcquireL();
williamr@2: 	IMPORT_C TAny* AllocL();
williamr@2: 	IMPORT_C TAny* LockL(TPageRef aRef);
williamr@2: 	IMPORT_C TPageRef AssignL(const TAny* aPage,TPageReclamation aReclamation=EPageDeleteOnly);
williamr@2: 	IMPORT_C void UpdateL(const TAny* aPage);
williamr@2: 	IMPORT_C void Unlock(const TAny* aPage,TPageChange aChange=EPageNoChange);
williamr@2: //
williamr@2: 	IMPORT_C TInt Flush();
williamr@2: 	IMPORT_C void FlushL();
williamr@2: 	IMPORT_C void Purge();
williamr@2: protected:
williamr@2: 	inline TCachePagePool();
williamr@2: 	inline TCachePagePool(CPageCache& aCache);
williamr@2: 	IMPORT_C void DoDeleteL(TPageRef aRef);
williamr@2: private:
williamr@2: 	virtual TPageRef ExtendL(const TAny* aPage,TPageReclamation aReclamation)=0;
williamr@2: 	virtual void WriteL(TPageRef aRef,const TAny* aPage,TPageChange aChange)=0;
williamr@2: 	virtual void ReadL(TPageRef aRef,TAny* aPage)=0;
williamr@2: //
williamr@2: 	static void DoAbandon(MPagePool& aPool);
williamr@2: 	static TCachePage* DoAllocL(CPageCache& aCache);
williamr@2: private:
williamr@2: 	CPageCache* iCache;
williamr@2: 	};
williamr@2: 
williamr@2: #include <s32page.inl>
williamr@2: #endif