Add SQLite3.status to call sqlite3_status

This function is useful for understanding the runtime performance of
sqlite.

This is a very thin layer on top of the sqlite3 library's function, so
it allows full usage of it from Ruby.

Author: wjlroe

ext/sqlite3/sqlite3.c

@@ -85,6 +85,22 @@ threadsafe_p(VALUE UNUSED(klass))
     return INT2NUM(sqlite3_threadsafe());
 }
 
+static VALUE
+status_p(VALUE UNUSED(klass), VALUE opArg, VALUE resetFlagArg)
+{
+    int op = NUM2INT(opArg);
+    bool resetFlag = TYPE(resetFlagArg) == T_TRUE;
+
+    int pCurrent = 0;
+    int pHighwater = 0;
+    sqlite3_status(op, &pCurrent, &pHighwater, resetFlag);
+
+    VALUE hash = rb_hash_new();
+    rb_hash_aset(hash, ID2SYM(rb_intern("current")), INT2FIX(pCurrent));
+    rb_hash_aset(hash, ID2SYM(rb_intern("highwater")), INT2FIX(pHighwater));
+    return hash;
+}
+
 void
 init_sqlite3_constants(void)
 {
@@ -164,6 +180,7 @@ Init_sqlite3_native(void)
     rb_define_singleton_method(mSqlite3, "sqlcipher?", using_sqlcipher, 0);
     rb_define_singleton_method(mSqlite3, "libversion", libversion, 0);
     rb_define_singleton_method(mSqlite3, "threadsafe", threadsafe_p, 0);
+    rb_define_singleton_method(mSqlite3, "status", status_p, 2);
     rb_define_const(mSqlite3, "SQLITE_VERSION", rb_str_new2(SQLITE_VERSION));
     rb_define_const(mSqlite3, "SQLITE_VERSION_NUMBER", INT2FIX(SQLITE_VERSION_NUMBER));
     rb_define_const(mSqlite3, "SQLITE_LOADED_VERSION", rb_str_new2(sqlite3_libversion()));

lib/sqlite3/constants.rb

@@ -116,5 +116,18 @@ module ErrorCode
       # sqlite_step() has finished executing
       DONE = 101
     end
+
+    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.
+    end
   end
 end

test/test_sqlite3.rb

@@ -21,5 +21,11 @@ def test_threadsafe?
     def test_compiled_version_and_loaded_version
       assert_equal(SQLite3::SQLITE_VERSION, SQLite3::SQLITE_LOADED_VERSION)
     end
+
+    def test_status
+      status = SQLite3.status(SQLite3::Constants::Status::MEMORY_USED, false)
+      assert_not_nil(status.fetch(:current))
+      assert_not_nil(status.fetch(:highwater))
+    end
   end
 end