1.1 --- a/epoc32/include/s32page.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/s32page.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,283 @@
1.4 -s32page.h
1.5 +// Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +// All rights reserved.
1.7 +// This component and the accompanying materials are made available
1.8 +// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
1.9 +// which accompanies this distribution, and is available
1.10 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 +//
1.12 +// Initial Contributors:
1.13 +// Nokia Corporation - initial contribution.
1.14 +//
1.15 +// Contributors:
1.16 +//
1.17 +// Description:
1.18 +//
1.19 +
1.20 +#if !defined(__S32PAGE_H__)
1.21 +#define __S32PAGE_H__
1.22 +#if !defined(__S32STRM_H__)
1.23 +#include <s32strm.h>
1.24 +#endif
1.25 +
1.26 +/** Size of the pages in the page pool. */
1.27 +const TInt KPoolPageSize=512;
1.28 +//
1.29 +const TUint32 KNullPageRefValue=0;
1.30 +
1.31 +/**
1.32 + * @publishedAll
1.33 + * @released
1.34 + * Encapsulates a page reference.
1.35 +
1.36 +A page reference is an integer value that can be used to identify a page.
1.37 + */
1.38 +class TPageRef
1.39 + {
1.40 +public:
1.41 + /** Default constructor. */
1.42 + inline TPageRef() {}
1.43 + inline TPageRef(TUint32 aValue);
1.44 +//
1.45 + inline TBool operator==(TPageRef aRef) const;
1.46 + inline TBool operator!=(TPageRef aRef) const;
1.47 +//
1.48 + inline void ExternalizeL(RWriteStream& aStream) const;
1.49 + inline void InternalizeL(RReadStream& aStream);
1.50 +//
1.51 + inline TUint32 Value() const;
1.52 +private:
1.53 + TUint32 iVal;
1.54 + };
1.55 +#if defined(__NO_CLASS_CONSTS__)
1.56 +#define KNullPageRef TPageRef(KNullPageRefValue)
1.57 +#else
1.58 +/** Defines a null page reference. */
1.59 +const TPageRef KNullPageRef=TPageRef(KNullPageRefValue);
1.60 +#endif
1.61 +
1.62 +class MPagePool;
1.63 +/** Typedef to define a function that abandons pages in page pool. It is used by
1.64 +MPagePool::AcquireL().
1.65 +
1.66 +@see MPagePool::AcquireL() */
1.67 +typedef void (*TPageAbandonFunction)(MPagePool& aPool);
1.68 +
1.69 +/** Flags that define how allocated pages can be reclaimed.
1.70 +
1.71 +A BTree can locate some pages even when the tree is broken, but not all. The
1.72 +ones it cannot track must be tracked by the page pool in order to reclaim
1.73 +the storage if the tree breaks. */
1.74 +enum TPageReclamation
1.75 + /** The page can be deleted, but its space not reclaimed.
1.76 +
1.77 + The page pool will not track these pages, so to retrieve the space the page
1.78 + must be deleted explicitly. */
1.79 + {EPageDeleteOnly,
1.80 + /** Page can be reclaimed.
1.81 +
1.82 + The page pool will track these pages, and will be able to reclaim the pages
1.83 + when, for example, RStorePagePool::ReclaimL() is called. */
1.84 + EPageReclaimable};
1.85 +
1.86 +/** Flags that define how a page should be treated when it is unlocked. */
1.87 +enum TPageChange
1.88 + /** Unlock only. */
1.89 + {EPageNoChange,
1.90 + /** Mark the page as dirty. */
1.91 + EPageDirty,
1.92 + /** Mark the page as needing a safe update. */
1.93 + EPageUpdate,
1.94 + /** Discard the page. */
1.95 + EPageAbandon=-1};
1.96 +
1.97 +
1.98 +/**
1.99 + * @publishedAll
1.100 + * @released
1.101 + * Interface to a page pool, the storage abstraction used by the B-trees API.
1.102 +
1.103 +The interface is abstract and handles pages as TAny pointers. It is left to
1.104 +derived classes to implement page storage in a particular storage medium,
1.105 +such as memory or disk.
1.106 +*/
1.107 +class MPagePool
1.108 + {
1.109 +public:
1.110 + IMPORT_C void PushL();
1.111 + inline void Pop();
1.112 +
1.113 + /** Returns a function that abandons all locked pages for this page pool.
1.114 +
1.115 + @return A function that abandons all locked pages for this page pool. */
1.116 + virtual TPageAbandonFunction AcquireL()=0;
1.117 +//
1.118 + virtual TAny* AllocL()=0;
1.119 +
1.120 + /** Locks a page and returns a pointer to it.
1.121 +
1.122 + @param aRef Reference to the page to lock
1.123 + @return Locked page */
1.124 + virtual TAny* LockL(TPageRef aRef)=0;
1.125 +//
1.126 + virtual TPageRef AssignL(const TAny* aPage,TPageReclamation aReclamation=EPageDeleteOnly)=0;
1.127 +
1.128 + /** Updates a page.
1.129 +
1.130 + This can be used for cached pages that may have become outdated.
1.131 +
1.132 + @param aPage Page to update */
1.133 + virtual void UpdateL(const TAny* aPage)=0;
1.134 +
1.135 + /** Unlocks a page.
1.136 +
1.137 + @param aPage Page to unlock
1.138 + @param aChange How the page should be treated once it is unlocked */
1.139 + virtual void Unlock(const TAny* aPage,TPageChange aChange=EPageNoChange)=0;
1.140 +//
1.141 + IMPORT_C void Delete(TPageRef aRef);
1.142 + IMPORT_C void DeleteL(TPageRef aRef);
1.143 +protected:
1.144 + virtual void DoDeleteL(TPageRef aRef)=0;
1.145 + };
1.146 +
1.147 +/**
1.148 + * @publishedAll
1.149 + * @released
1.150 + * Uses memory to implement the MPagePool page pool interface.
1.151 +
1.152 +The class allocates pages from the default heap, storing them in an array.
1.153 +This pool is not persistent.
1.154 + */
1.155 +class CMemPagePool : public CBase,public MPagePool
1.156 + {
1.157 +public:
1.158 + IMPORT_C static CMemPagePool* NewL();
1.159 + IMPORT_C static CMemPagePool* NewLC();
1.160 + IMPORT_C CMemPagePool();
1.161 + IMPORT_C ~CMemPagePool();
1.162 +//
1.163 + IMPORT_C TPageAbandonFunction AcquireL();
1.164 + IMPORT_C TAny* AllocL();
1.165 + IMPORT_C TAny* LockL(TPageRef aRef);
1.166 + IMPORT_C TPageRef AssignL(const TAny* aPage,TPageReclamation aReclamation=EPageDeleteOnly);
1.167 + IMPORT_C void UpdateL(const TAny* aPage);
1.168 + IMPORT_C void Unlock(const TAny* aPage,TPageChange aChange=EPageNoChange);
1.169 +protected:
1.170 + IMPORT_C void DoDeleteL(TPageRef aRef);
1.171 +private:
1.172 + TAny*& PageL(TPageRef aRef);
1.173 + static void DoAbandon(MPagePool& aPool);
1.174 +private:
1.175 + CArrayFixSeg<TAny*> iPages;
1.176 + };
1.177 +//
1.178 +#if defined(_DEBUG)&&!defined(__PAGE_CACHE_STATS)
1.179 +//#define __PAGE_CACHE_STATS
1.180 +#endif
1.181 +//
1.182 +class TCachePage;
1.183 +struct SCachePage;
1.184 +class TCachePagePool;
1.185 +
1.186 +/**
1.187 + * @publishedAll
1.188 + * @released
1.189 + * Provides a cache for page pools.
1.190 +
1.191 +Persistent page pools rely on a cache to provide in-memory space for their
1.192 +pages and to cache frequently accessed pages.
1.193 +*/
1.194 +class CPageCache : public CBase
1.195 + {
1.196 +public:
1.197 + enum {EDefaultPages=20};
1.198 +#if defined(__PAGE_CACHE_STATS)
1.199 +
1.200 + /**
1.201 + * @publishedAll
1.202 + * @released
1.203 + */
1.204 + class TStats
1.205 + {
1.206 + public:
1.207 + inline TInt Requests() const;
1.208 + inline TInt Hits() const;
1.209 + inline TInt Misses() const;
1.210 + inline void Reset();
1.211 + private:
1.212 + inline void Hit();
1.213 + inline void Miss();
1.214 + private:
1.215 + TInt iRequests;
1.216 + TInt iMisses;
1.217 + private:
1.218 + friend class CPageCache;
1.219 + };
1.220 +#endif
1.221 +public:
1.222 + IMPORT_C static CPageCache* NewL(TInt aPages=EDefaultPages);
1.223 + IMPORT_C static CPageCache* NewLC(TInt aPages=EDefaultPages);
1.224 + IMPORT_C CPageCache();
1.225 + IMPORT_C void ConstructL(TInt aPages=EDefaultPages);
1.226 + IMPORT_C ~CPageCache();
1.227 +//
1.228 +#if defined(__PAGE_CACHE_STATS)
1.229 + inline TStats& Stats();
1.230 + inline const TStats& Stats() const;
1.231 +#endif
1.232 +private:
1.233 + TCachePage* Find(TCachePagePool* aPool,TPageRef aRef);
1.234 +private:
1.235 + SCachePage* iPages;
1.236 + SCachePage* iEnd;
1.237 + TDblQue<TCachePage> iFree;
1.238 +#if defined(__PAGE_CACHE_STATS)
1.239 + TStats iStats;
1.240 +#endif
1.241 +private:
1.242 + friend class TCachePagePool;
1.243 + };
1.244 +
1.245 +/**
1.246 + * @publishedAll
1.247 + * @released
1.248 + * Provides a page pool with cached pages.
1.249 +
1.250 +It is an intermediary class, used in the definition of page pools that use
1.251 +a cache, such as RFilePagePool and RStorePagePool.
1.252 +
1.253 +@see RFilePagePool
1.254 +@see RStorePagePool
1.255 +*/
1.256 +class TCachePagePool : public MPagePool
1.257 + {
1.258 +public:
1.259 + inline void Set(CPageCache& aCache);
1.260 +//
1.261 + IMPORT_C TPageAbandonFunction AcquireL();
1.262 + IMPORT_C TAny* AllocL();
1.263 + IMPORT_C TAny* LockL(TPageRef aRef);
1.264 + IMPORT_C TPageRef AssignL(const TAny* aPage,TPageReclamation aReclamation=EPageDeleteOnly);
1.265 + IMPORT_C void UpdateL(const TAny* aPage);
1.266 + IMPORT_C void Unlock(const TAny* aPage,TPageChange aChange=EPageNoChange);
1.267 +//
1.268 + IMPORT_C TInt Flush();
1.269 + IMPORT_C void FlushL();
1.270 + IMPORT_C void Purge();
1.271 +protected:
1.272 + inline TCachePagePool();
1.273 + inline TCachePagePool(CPageCache& aCache);
1.274 + IMPORT_C void DoDeleteL(TPageRef aRef);
1.275 +private:
1.276 + virtual TPageRef ExtendL(const TAny* aPage,TPageReclamation aReclamation)=0;
1.277 + virtual void WriteL(TPageRef aRef,const TAny* aPage,TPageChange aChange)=0;
1.278 + virtual void ReadL(TPageRef aRef,TAny* aPage)=0;
1.279 +//
1.280 + static void DoAbandon(MPagePool& aPool);
1.281 + static TCachePage* DoAllocL(CPageCache& aCache);
1.282 +private:
1.283 + CPageCache* iCache;
1.284 + };
1.285 +
1.286 +#include <s32page.inl>
1.287 +#endif