modernc.org/cc@v1.0.1/v2/testdata/_sqlite/src/pcache.h (about)

     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    PCache *pCache;                /* PRIVATE: Cache that owns this page */
    30    PgHdr *pDirty;                 /* Transient list of dirty sorted by pgno */
    31    Pager *pPager;                 /* The pager this page is part of */
    32    Pgno pgno;                     /* Page number for this page */
    33  #ifdef SQLITE_CHECK_PAGES
    34    u32 pageHash;                  /* Hash of page content */
    35  #endif
    36    u16 flags;                     /* PGHDR flags defined below */
    37  
    38    /**********************************************************************
    39    ** Elements above, except pCache, are public.  All that follow are 
    40    ** private to pcache.c and should not be accessed by other modules.
    41    ** pCache is grouped with the public elements for efficiency.
    42    */
    43    i16 nRef;                      /* Number of users of this page */
    44    PgHdr *pDirtyNext;             /* Next element in list of dirty pages */
    45    PgHdr *pDirtyPrev;             /* Previous element in list of dirty pages */
    46                            /* NB: pDirtyNext and pDirtyPrev are undefined if the
    47                            ** PgHdr object is not dirty */
    48  };
    49  
    50  /* Bit values for PgHdr.flags */
    51  #define PGHDR_CLEAN           0x001  /* Page not on the PCache.pDirty list */
    52  #define PGHDR_DIRTY           0x002  /* Page is on the PCache.pDirty list */
    53  #define PGHDR_WRITEABLE       0x004  /* Journaled and ready to modify */
    54  #define PGHDR_NEED_SYNC       0x008  /* Fsync the rollback journal before
    55                                       ** writing this page to the database */
    56  #define PGHDR_DONT_WRITE      0x010  /* Do not write content to disk */
    57  #define PGHDR_MMAP            0x020  /* This is an mmap page object */
    58  
    59  #define PGHDR_WAL_APPEND      0x040  /* Appended to wal file */
    60  
    61  /* Initialize and shutdown the page cache subsystem */
    62  int sqlite3PcacheInitialize(void);
    63  void sqlite3PcacheShutdown(void);
    64  
    65  /* Page cache buffer management:
    66  ** These routines implement SQLITE_CONFIG_PAGECACHE.
    67  */
    68  void sqlite3PCacheBufferSetup(void *, int sz, int n);
    69  
    70  /* Create a new pager cache.
    71  ** Under memory stress, invoke xStress to try to make pages clean.
    72  ** Only clean and unpinned pages can be reclaimed.
    73  */
    74  int sqlite3PcacheOpen(
    75    int szPage,                    /* Size of every page */
    76    int szExtra,                   /* Extra space associated with each page */
    77    int bPurgeable,                /* True if pages are on backing store */
    78    int (*xStress)(void*, PgHdr*), /* Call to try to make pages clean */
    79    void *pStress,                 /* Argument to xStress */
    80    PCache *pToInit                /* Preallocated space for the PCache */
    81  );
    82  
    83  /* Modify the page-size after the cache has been created. */
    84  int sqlite3PcacheSetPageSize(PCache *, int);
    85  
    86  /* Return the size in bytes of a PCache object.  Used to preallocate
    87  ** storage space.
    88  */
    89  int sqlite3PcacheSize(void);
    90  
    91  /* One release per successful fetch.  Page is pinned until released.
    92  ** Reference counted. 
    93  */
    94  sqlite3_pcache_page *sqlite3PcacheFetch(PCache*, Pgno, int createFlag);
    95  int sqlite3PcacheFetchStress(PCache*, Pgno, sqlite3_pcache_page**);
    96  PgHdr *sqlite3PcacheFetchFinish(PCache*, Pgno, sqlite3_pcache_page *pPage);
    97  void sqlite3PcacheRelease(PgHdr*);
    98  
    99  void sqlite3PcacheDrop(PgHdr*);         /* Remove page from cache */
   100  void sqlite3PcacheMakeDirty(PgHdr*);    /* Make sure page is marked dirty */
   101  void sqlite3PcacheMakeClean(PgHdr*);    /* Mark a single page as clean */
   102  void sqlite3PcacheCleanAll(PCache*);    /* Mark all dirty list pages as clean */
   103  void sqlite3PcacheClearWritable(PCache*);
   104  
   105  /* Change a page number.  Used by incr-vacuum. */
   106  void sqlite3PcacheMove(PgHdr*, Pgno);
   107  
   108  /* Remove all pages with pgno>x.  Reset the cache if x==0 */
   109  void sqlite3PcacheTruncate(PCache*, Pgno x);
   110  
   111  /* Get a list of all dirty pages in the cache, sorted by page number */
   112  PgHdr *sqlite3PcacheDirtyList(PCache*);
   113  
   114  /* Reset and close the cache object */
   115  void sqlite3PcacheClose(PCache*);
   116  
   117  /* Clear flags from pages of the page cache */
   118  void sqlite3PcacheClearSyncFlags(PCache *);
   119  
   120  /* Discard the contents of the cache */
   121  void sqlite3PcacheClear(PCache*);
   122  
   123  /* Return the total number of outstanding page references */
   124  int sqlite3PcacheRefCount(PCache*);
   125  
   126  /* Increment the reference count of an existing page */
   127  void sqlite3PcacheRef(PgHdr*);
   128  
   129  int sqlite3PcachePageRefcount(PgHdr*);
   130  
   131  /* Return the total number of pages stored in the cache */
   132  int sqlite3PcachePagecount(PCache*);
   133  
   134  #if defined(SQLITE_CHECK_PAGES) || defined(SQLITE_DEBUG)
   135  /* Iterate through all dirty pages currently stored in the cache. This
   136  ** interface is only available if SQLITE_CHECK_PAGES is defined when the 
   137  ** library is built.
   138  */
   139  void sqlite3PcacheIterateDirty(PCache *pCache, void (*xIter)(PgHdr *));
   140  #endif
   141  
   142  #if defined(SQLITE_DEBUG)
   143  /* Check invariants on a PgHdr object */
   144  int sqlite3PcachePageSanity(PgHdr*);
   145  #endif
   146  
   147  /* Set and get the suggested cache-size for the specified pager-cache.
   148  **
   149  ** If no global maximum is configured, then the system attempts to limit
   150  ** the total number of pages cached by purgeable pager-caches to the sum
   151  ** of the suggested cache-sizes.
   152  */
   153  void sqlite3PcacheSetCachesize(PCache *, int);
   154  #ifdef SQLITE_TEST
   155  int sqlite3PcacheGetCachesize(PCache *);
   156  #endif
   157  
   158  /* Set or get the suggested spill-size for the specified pager-cache.
   159  **
   160  ** The spill-size is the minimum number of pages in cache before the cache
   161  ** will attempt to spill dirty pages by calling xStress.
   162  */
   163  int sqlite3PcacheSetSpillsize(PCache *, int);
   164  
   165  /* Free up as much memory as possible from the page cache */
   166  void sqlite3PcacheShrink(PCache*);
   167  
   168  #ifdef SQLITE_ENABLE_MEMORY_MANAGEMENT
   169  /* Try to return memory used by the pcache module to the main memory heap */
   170  int sqlite3PcacheReleaseMemory(int);
   171  #endif
   172  
   173  #ifdef SQLITE_TEST
   174  void sqlite3PcacheStats(int*,int*,int*,int*);
   175  #endif
   176  
   177  void sqlite3PCacheSetDefault(void);
   178  
   179  /* Return the header size */
   180  int sqlite3HeaderSizePcache(void);
   181  int sqlite3HeaderSizePcache1(void);
   182  
   183  /* Number of dirty pages as a percentage of the configured cache size */
   184  int sqlite3PCachePercentDirty(PCache*);
   185  
   186  #endif /* _PCACHE_H_ */