From a1ddbec50f5376f2e3ab67ce192bf8e242b07bdb Mon Sep 17 00:00:00 2001 From: Mike Dalessio Date: Tue, 16 Apr 2024 10:37:35 -0400 Subject: [PATCH] doc: document SQLite3::Constants::Status and add to the changelog --- CHANGELOG.md | 1 + lib/sqlite3/constants.rb | 61 +++++++++++++++++++++++++++++++++------- 2 files changed, 52 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f6912852..863695df 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/lib/sqlite3/constants.rb b/lib/sqlite3/constants.rb index beff74db..77e82e19 100644 --- a/lib/sqlite3/constants.rb +++ b/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