Return to pcache.h CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / sqlite3 / src

sqlite3

    1: /*
    2: ** 2008 August 05
    3: **
    4: ** The author disclaims copyright to this source code.  In place of
    5: ** a legal notice, here is a blessing:
    6: **
    7: **    May you do good and not evil.
    8: **    May you find forgiveness for yourself and forgive others.
    9: **    May you share freely, never taking more than you give.
   10: **
   11: *************************************************************************
   12: ** This header file defines the interface that the sqlite page cache
   13: ** subsystem. 
   14: */
   15: 
   16: #ifndef _PCACHE_H_
   17: 
   18: typedef struct PgHdr PgHdr;
   19: typedef struct PCache PCache;
   20: 
   21: /*
   22: ** Every page in the cache is controlled by an instance of the following
   23: ** structure.
   24: */
   25: struct PgHdr {
   26:   sqlite3_pcache_page *pPage;    /* Pcache object page handle */
   27:   void *pData;                   /* Page data */
   28:   void *pExtra;                  /* Extra content */
   29:   PgHdr *pDirty;                 /* Transient list of dirty pages */
   30:   Pgno pgno;                     /* Page number for this page */
   31:   Pager *pPager;                 /* The pager this page is part of */
   32: #ifdef SQLITE_CHECK_PAGES
   33:   u32 pageHash;                  /* Hash of page content */
   34: #endif
   35:   u16 flags;                     /* PGHDR flags defined below */
   36: 
   37:   /**********************************************************************
   38:   ** Elements above are public.  All that follows is private to pcache.c
   39:   ** and should not be accessed by other modules.
   40:   */
   41:   i16 nRef;                      /* Number of users of this page */
   42:   PCache *pCache;                /* Cache that owns this page */
   43: 
   44:   PgHdr *pDirtyNext;             /* Next element in list of dirty pages */
   45:   PgHdr *pDirtyPrev;             /* Previous element in list of dirty pages */
   46: };
   47: 
   48: /* Bit values for PgHdr.flags */
   49: #define PGHDR_DIRTY             0x002  /* Page has changed */
   50: #define PGHDR_NEED_SYNC         0x004  /* Fsync the rollback journal before
   51:                                        ** writing this page to the database */
   52: #define PGHDR_NEED_READ         0x008  /* Content is unread */
   53: #define PGHDR_REUSE_UNLIKELY    0x010  /* A hint that reuse is unlikely */
   54: #define PGHDR_DONT_WRITE        0x020  /* Do not write content to disk */
   55: 
   56: /* Initialize and shutdown the page cache subsystem */
   57: int sqlite3PcacheInitialize(void);
   58: void sqlite3PcacheShutdown(void);
   59: 
   60: /* Page cache buffer management:
   61: ** These routines implement SQLITE_CONFIG_PAGECACHE.
   62: */
   63: void sqlite3PCacheBufferSetup(void *, int sz, int n);
   64: 
   65: /* Create a new pager cache.
   66: ** Under memory stress, invoke xStress to try to make pages clean.
   67: ** Only clean and unpinned pages can be reclaimed.
   68: */
   69: void sqlite3PcacheOpen(
   70:   int szPage,                    /* Size of every page */
   71:   int szExtra,                   /* Extra space associated with each page */
   72:   int bPurgeable,                /* True if pages are on backing store */
   73:   int (*xStress)(void*, PgHdr*), /* Call to try to make pages clean */
   74:   void *pStress,                 /* Argument to xStress */
   75:   PCache *pToInit                /* Preallocated space for the PCache */
   76: );
   77: 
   78: /* Modify the page-size after the cache has been created. */
   79: void sqlite3PcacheSetPageSize(PCache *, int);
   80: 
   81: /* Return the size in bytes of a PCache object.  Used to preallocate
   82: ** storage space.
   83: */
   84: int sqlite3PcacheSize(void);
   85: 
   86: /* One release per successful fetch.  Page is pinned until released.
   87: ** Reference counted. 
   88: */
   89: int sqlite3PcacheFetch(PCache*, Pgno, int createFlag, PgHdr**);
   90: void sqlite3PcacheRelease(PgHdr*);
   91: 
   92: void sqlite3PcacheDrop(PgHdr*);         /* Remove page from cache */
   93: void sqlite3PcacheMakeDirty(PgHdr*);    /* Make sure page is marked dirty */
   94: void sqlite3PcacheMakeClean(PgHdr*);    /* Mark a single page as clean */
   95: void sqlite3PcacheCleanAll(PCache*);    /* Mark all dirty list pages as clean */
   96: 
   97: /* Change a page number.  Used by incr-vacuum. */
   98: void sqlite3PcacheMove(PgHdr*, Pgno);
   99: 
  100: /* Remove all pages with pgno>x.  Reset the cache if x==0 */
  101: void sqlite3PcacheTruncate(PCache*, Pgno x);
  102: 
  103: /* Get a list of all dirty pages in the cache, sorted by page number */
  104: PgHdr *sqlite3PcacheDirtyList(PCache*);
  105: 
  106: /* Reset and close the cache object */
  107: void sqlite3PcacheClose(PCache*);
  108: 
  109: /* Clear flags from pages of the page cache */
  110: void sqlite3PcacheClearSyncFlags(PCache *);
  111: 
  112: /* Discard the contents of the cache */
  113: void sqlite3PcacheClear(PCache*);
  114: 
  115: /* Return the total number of outstanding page references */
  116: int sqlite3PcacheRefCount(PCache*);
  117: 
  118: /* Increment the reference count of an existing page */
  119: void sqlite3PcacheRef(PgHdr*);
  120: 
  121: int sqlite3PcachePageRefcount(PgHdr*);
  122: 
  123: /* Return the total number of pages stored in the cache */
  124: int sqlite3PcachePagecount(PCache*);
  125: 
  126: #if defined(SQLITE_CHECK_PAGES) || defined(SQLITE_DEBUG)
  127: /* Iterate through all dirty pages currently stored in the cache. This
  128: ** interface is only available if SQLITE_CHECK_PAGES is defined when the 
  129: ** library is built.
  130: */
  131: void sqlite3PcacheIterateDirty(PCache *pCache, void (*xIter)(PgHdr *));
  132: #endif
  133: 
  134: /* Set and get the suggested cache-size for the specified pager-cache.
  135: **
  136: ** If no global maximum is configured, then the system attempts to limit
  137: ** the total number of pages cached by purgeable pager-caches to the sum
  138: ** of the suggested cache-sizes.
  139: */
  140: void sqlite3PcacheSetCachesize(PCache *, int);
  141: #ifdef SQLITE_TEST
  142: int sqlite3PcacheGetCachesize(PCache *);
  143: #endif
  144: 
  145: /* Free up as much memory as possible from the page cache */
  146: void sqlite3PcacheShrink(PCache*);
  147: 
  148: #ifdef SQLITE_ENABLE_MEMORY_MANAGEMENT
  149: /* Try to return memory used by the pcache module to the main memory heap */
  150: int sqlite3PcacheReleaseMemory(int);
  151: #endif
  152: 
  153: #ifdef SQLITE_TEST
  154: void sqlite3PcacheStats(int*,int*,int*,int*);
  155: #endif
  156: 
  157: void sqlite3PCacheSetDefault(void);
  158: 
  159: #endif /* _PCACHE_H_ */