doc: document SQLite3::Constants::Status

and add to the changelog

CHANGELOG.md

@@ -15,6 +15,7 @@ This release drops support for Ruby 2.7. [#453] @flavorjones
 - Support the `SUPER_JOURNAL` flag which is an alias for `MASTER_JOURNAL` as of sqlite 3.33.0. [#467] @flavorjones
 - `Statement#stat` and `Statement#memused` introduced to report statistics. [#461] @fractaledmind
 - `Statement#sql` and `Statement#expanded_sql` introduced to retrieve the SQL statement associated with the `Statement` object. [#293, #498] @tenderlove
+- `SQLite3.status` introduced to return run-time status and reset high-water marks. See `SQLite3::Constants::Status` for details. [#520] @wjlroe
 
 
 ### Improved

lib/sqlite3/constants.rb

@@ -117,17 +117,58 @@ module ErrorCode
  DONE = 101
  end
 
+ #
+ # CAPI3REF: Status Parameters
+ #
+ # These integer constants designate various run-time status parameters
+ # that can be returned by SQLite3.status
+ #
  module Status
- MEMORY_USED = 0 # This parameter is the current amount of memory checked out using sqlite3_malloc(), either directly or indirectly. The figure includes calls made to sqlite3_malloc() by the application and internal memory usage by the SQLite library. Auxiliary page-cache memory controlled by SQLITE_CONFIG_PAGECACHE is not included in this parameter. The amount returned is the sum of the allocation sizes as reported by the xSize method in sqlite3_mem_methods.
- PAGECACHE_USED = 1 # This parameter returns the number of pages used out of the pagecache memory allocator that was configured using SQLITE_CONFIG_PAGECACHE. The value returned is in pages, not in bytes.
- PAGECACHE_OVERFLOW = 2 # This parameter returns the number of bytes of page cache allocation which could not be satisfied by the SQLITE_CONFIG_PAGECACHE buffer and where forced to overflow to sqlite3_malloc(). The returned value includes allocations that overflowed because they where too large (they were larger than the "sz" parameter to SQLITE_CONFIG_PAGECACHE) and allocations that overflowed because no space was left in the page cache.
- SCRATCH_USED = 3 # NOT USED
- SCRATCH_OVERFLOW = 4 # NOT USED
- MALLOC_SIZE = 5 # This parameter records the largest memory allocation request handed to sqlite3_malloc() or sqlite3_realloc() (or their internal equivalents). Only the value returned in the *pHighwater parameter to sqlite3_status() is of interest. The value written into the *pCurrent parameter is undefined.
- PARSER_STACK = 6 # The *pHighwater parameter records the deepest parser stack. The *pCurrent value is undefined. The *pHighwater value is only meaningful if SQLite is compiled with YYTRACKMAXSTACKDEPTH.
- PAGECACHE_SIZE = 7 # This parameter records the largest memory allocation request handed to the pagecache memory allocator. Only the value returned in the *pHighwater parameter to sqlite3_status() is of interest. The value written into the *pCurrent parameter is undefined.
- SCRATCH_SIZE = 8 # NOT USED
- MALLOC_COUNT = 9 # This parameter records the number of separate memory allocations currently checked out.
+ # This parameter is the current amount of memory checked out using sqlite3_malloc(), either
+ # directly or indirectly. The figure includes calls made to sqlite3_malloc() by the
+ # application and internal memory usage by the SQLite library. Auxiliary page-cache memory
+ # controlled by SQLITE_CONFIG_PAGECACHE is not included in this parameter. The amount returned
+ # is the sum of the allocation sizes as reported by the xSize method in sqlite3_mem_methods.
+ MEMORY_USED = 0
+
+ # This parameter returns the number of pages used out of the pagecache memory allocator that
+ # was configured using SQLITE_CONFIG_PAGECACHE. The value returned is in pages, not in bytes.
+ PAGECACHE_USED = 1
+
+ # This parameter returns the number of bytes of page cache allocation which could not be
+ # satisfied by the SQLITE_CONFIG_PAGECACHE buffer and where forced to overflow to
+ # sqlite3_malloc(). The returned value includes allocations that overflowed because they where
+ # too large (they were larger than the "sz" parameter to SQLITE_CONFIG_PAGECACHE) and
+ # allocations that overflowed because no space was left in the page cache.
+ PAGECACHE_OVERFLOW = 2
+
+ # NOT USED
+ SCRATCH_USED = 3
+
+ # NOT USED
+ SCRATCH_OVERFLOW = 4
+
+ # This parameter records the largest memory allocation request handed to sqlite3_malloc() or
+ # sqlite3_realloc() (or their internal equivalents). Only the value returned in the
+ # *pHighwater parameter to sqlite3_status() is of interest. The value written into the
+ # *pCurrent parameter is undefined.
+ MALLOC_SIZE = 5
+
+ # The *pHighwater parameter records the deepest parser stack. The *pCurrent value is
+ # undefined. The *pHighwater value is only meaningful if SQLite is compiled with
+ # YYTRACKMAXSTACKDEPTH.
+ PARSER_STACK = 6
+
+ # This parameter records the largest memory allocation request handed to the pagecache memory
+ # allocator. Only the value returned in the *pHighwater parameter to sqlite3_status() is of
+ # interest. The value written into the *pCurrent parameter is undefined.
+ PAGECACHE_SIZE = 7
+
+ # NOT USED
+ SCRATCH_SIZE = 8
+
+ # This parameter records the number of separate memory allocations currently checked out.
+ MALLOC_COUNT = 9
  end
  end
 end