Method: Extralite.on_progress

Defined in:
ext/extralite/database.c

.on_progress(**opts) { ... } ⇒ Extralite::Database

Installs or removes a global progress handler that will be executed periodically while a query is running. This method can be used to support switching between fibers and threads or implementing timeouts for running queries.

This method sets the progress handler settings and behaviour for all subsequently created Database instances. Calling this method will have no effect on already existing Database instances

The period parameter specifies the approximate number of SQLite virtual machine instructions that are evaluated between successive invocations of the progress handler. A period of less than 1 removes the progress handler. The default period value is 1000.

The optional tick parameter specifies the granularity of how often the progress handler is called. The default tick value is 10, which means that Extralite's underlying progress callback will be called every 10 SQLite VM instructions. The given progress proc, however, will be only called every period (cumulative) VM instructions. This allows the progress handler to work correctly also when running simple queries that don't include many VM instructions. If the tick value is greater than the period value it is automatically capped to the period value.

The mode parameter controls the progress handler mode, which is one of the following:

  • :normal (default): the progress handler proc is invoked on query progress.
  • :once: the progress handler proc is invoked only once, when preparing the query.
  • :at_least_once: the progress handler proc is invoked when prearing the query, and on query progress.

The progress handler is called also when the database is busy. This lets the application perform work while waiting for the database to become unlocked, or implement a timeout. Note that setting the database's busy_timeout after setting a progress handler may lead to undefined behaviour in a concurrent application. When busy, the progress handler proc is passed true as the first argument.

When the progress handler is set, the gvl release threshold value is set to -1, which means that the GVL will not be released at all when preparing or running queries. It is the application's responsibility to let other threads or fibers run by calling e.g. Thread.pass:

Extralite.on_progress do
  do_something_interesting
  Thread.pass # let other threads run
end

Yields:

  • []

Parameters:

  • period (Integer) —

    progress handler period

  • opts (Hash) —

    progress options

Returns:



1347
1348
1349
1350
1351
1352
1353
 
# File 'ext/extralite/database.c', line 1347

VALUE Extralite_on_progress(int argc, VALUE *argv, VALUE self) {
  VALUE opts;

  rb_scan_args(argc, argv, "00:", &opts);
  global_progress_handler = parse_progress_handler_opts(opts);
  return self;
}