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