Re: [sqlite] Tcl bindings doc update request

[Rolf Ade]

I certainly apologzize, to rise this a third time; I will stop to do it
again.

Still, I think the documentation of the busy method of the Tcl interface
to sqlite

http://sqlite.org/tclsqlite.html#busy

lacks the information, that the callback procedure will be called with
one argument.


Rolf Ade  writes:
> I apologzize to rise this again, it may have fallen under the radar for
> some reason. It is minor, too.
>
> The documentation of the busy method of the Tcl interface to sqlite
>
> http://sqlite.org/tclsqlite.html#busy
>
> doesn't tell, that the callback procedure is called with one arg, the
> "number of times that the busy handler has been invoked previously for
> the same locking event" (as the documentation sqlite3_busy_handler() at 
> https://www.sqlite.org/c3ref/busy_handler.html words it).
>
> The documentation also doesn't note, how the timeout and busy methods
> interfere.
>
> The appended script illustrates the current implementation.
>
> rolf
>
> package require sqlite3
>
> sqlite3 one tmp.db
> one eval {
> CREATE TABLE IF NOT EXISTS some(value text);
> INSERT INTO some VALUES('foo');
> BEGIN IMMEDIATE TRANSACTION
> }
>
> proc busyhandler {args} {
> global counter
> puts "args: '$args'"
> incr counter
> if {$counter > 3} {
> return 1
> }
> return 0
> }
>
> sqlite3 two tmp.db
> two busy busyhandler
>
> catch {two eval { DELETE FROM some }} errMsg
> puts $errMsg
> two timeout 500
> catch {two eval { DELETE FROM some }} errMsg
> puts $errMsg
> two busy busyhandler
> catch {two eval { DELETE FROM some }} errMsg
> puts $errMsg
>
>
>
> Rolf Ade  writes:
>> The documentation of the busy method at
>>
>> http://sqlite.org/tclsqlite.html#busy
>>
>> should be more specific, with regards of the arguments of the Tcl
>> callback procedure.
>>
>> The documentation currently reads:
>>
>> The "busy" method, like "timeout", only comes into play when the
>> database is locked. But the "busy" method gives the programmer much
>> more control over what action to take. The "busy" method specifies a
>> callback Tcl procedure that is invoked whenever SQLite tries to open
>> a locked database. This callback can do whatever is desired.
>> Presumably, the callback will do some other useful work for a short
>> while (such as service GUI events) then return so that the lock can
>> be tried again. The callback procedure should return "0" if it wants
>> SQLite to try again to open the database and should return "1" if it
>> wants SQLite to abandon the current operation.
>>
>> This doesn't specify, what arguments the Tcl callback procedure must
>> expect. Turns out, that the proc is called with one argument (the number
>> of how much the busy callback was already called for the current lock
>> situation, it seems). That should be explictly written in the
>> documentation, since it doesn't seem clearly obvious.
>>
>> What must be obvious is, that English is a foreign language to me.
>> Therefor, I'm shy to propose a phrase.
>>
>> Another plea, since I'm already writing: It isn't immediate and without
>> any doubt clear, how the "timeout" and the "busy" methods play together,
>> if both are used. I suspect, the timeout, if given, determines, how long
>> it lasts until the busy callback is called (and that for every round, if
>> the busy callback returned "0") but if it is this way (or not) isn't
>> said somewhere, if I see right.
>>
>> rolf
>>
>> ___
>> sqlite-users mailing list
>> sqlite-users@mailinglists.sqlite.org
>> http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
>
> ___
> sqlite-users mailing list
> sqlite-users@mailinglists.sqlite.org
> http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users

___
sqlite-users mailing list
sqlite-users@mailinglists.sqlite.org
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users

Re: [sqlite] Tcl bindings doc update request

[Rolf Ade]

Rowan Worth  writes:
> On 28 October 2016 at 02:53, Rolf Ade  wrote:
>
>> Another plea, since I'm already writing: It isn't immediate and without
>> any doubt clear, how the "timeout" and the "busy" methods play together,
>> if both are used. I suspect, the timeout, if given, determines, how long
>> it lasts until the busy callback is called (and that for every round, if
>> the busy callback returned "0") but if it is this way (or not) isn't
>> said somewhere, if I see right.
>>
>
> I'm not familiar with the TCL side of things, but in the C API "timeout"
> installs its own "busy" handler (which sleeps for a moment and then returns
> 0, or 1 if the timeout has been exceeded).
>
> There can only be one busy handler, so my guess is that the most recent
> call to "timeout" or "busy" will determine whether your busy handler or
> sqlite's timeout handler gets called.

It is in fact, as you suspected from knowing the C side.

This script illustrates this:

package require sqlite3

sqlite3 one tmp.db
one eval {
CREATE TABLE IF NOT EXISTS some(value text);
INSERT INTO some VALUES('foo');
BEGIN IMMEDIATE TRANSACTION
}

proc busyhandler {args} {
puts "busyhandler called"
}

sqlite3 two tmp.db
two busy busyhandler
two timeout 500
catch {two eval { DELETE FROM some }} errMsg
puts $errMsg
two busy busyhandler
catch {two eval { DELETE FROM some }} errMsg
puts $errMsg

rolf

___
sqlite-users mailing list
sqlite-users@mailinglists.sqlite.org
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users

Re: [sqlite] Tcl bindings doc update request

[Rolf Ade]

I apologzize to rise this again, it may have fallen under the radar for
some reason. It is minor, too.

The documentation of the busy method of the Tcl interface to sqlite

http://sqlite.org/tclsqlite.html#busy

doesn't tell, that the callback procedure is called with one arg, the
"number of times that the busy handler has been invoked previously for
the same locking event" (as the documentation sqlite3_busy_handler() at 
https://www.sqlite.org/c3ref/busy_handler.html words it).

The documentation also doesn't note, how the timeout and busy methods
interfere.

The appended script illustrates the current implementation.

rolf

package require sqlite3

sqlite3 one tmp.db
one eval {
CREATE TABLE IF NOT EXISTS some(value text);
INSERT INTO some VALUES('foo');
BEGIN IMMEDIATE TRANSACTION
}

proc busyhandler {args} {
global counter
puts "args: '$args'"
incr counter
if {$counter > 3} {
return 1
}
return 0
}

sqlite3 two tmp.db
two busy busyhandler

catch {two eval { DELETE FROM some }} errMsg
puts $errMsg
two timeout 500
catch {two eval { DELETE FROM some }} errMsg
puts $errMsg
two busy busyhandler
catch {two eval { DELETE FROM some }} errMsg
puts $errMsg



Rolf Ade  writes:
> The documentation of the busy method at
>
> http://sqlite.org/tclsqlite.html#busy
>
> should be more specific, with regards of the arguments of the Tcl
> callback procedure.
>
> The documentation currently reads:
>
> The "busy" method, like "timeout", only comes into play when the
> database is locked. But the "busy" method gives the programmer much
> more control over what action to take. The "busy" method specifies a
> callback Tcl procedure that is invoked whenever SQLite tries to open
> a locked database. This callback can do whatever is desired.
> Presumably, the callback will do some other useful work for a short
> while (such as service GUI events) then return so that the lock can
> be tried again. The callback procedure should return "0" if it wants
> SQLite to try again to open the database and should return "1" if it
> wants SQLite to abandon the current operation.
>
> This doesn't specify, what arguments the Tcl callback procedure must
> expect. Turns out, that the proc is called with one argument (the number
> of how much the busy callback was already called for the current lock
> situation, it seems). That should be explictly written in the
> documentation, since it doesn't seem clearly obvious.
>
> What must be obvious is, that English is a foreign language to me.
> Therefor, I'm shy to propose a phrase.
>
> Another plea, since I'm already writing: It isn't immediate and without
> any doubt clear, how the "timeout" and the "busy" methods play together,
> if both are used. I suspect, the timeout, if given, determines, how long
> it lasts until the busy callback is called (and that for every round, if
> the busy callback returned "0") but if it is this way (or not) isn't
> said somewhere, if I see right.
>
> rolf
>
> ___
> sqlite-users mailing list
> sqlite-users@mailinglists.sqlite.org
> http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users

___
sqlite-users mailing list
sqlite-users@mailinglists.sqlite.org
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users

Re: [sqlite] Tcl bindings doc update request

[Rowan Worth]

On 28 October 2016 at 02:53, Rolf Ade  wrote:

> Another plea, since I'm already writing: It isn't immediate and without
> any doubt clear, how the "timeout" and the "busy" methods play together,
> if both are used. I suspect, the timeout, if given, determines, how long
> it lasts until the busy callback is called (and that for every round, if
> the busy callback returned "0") but if it is this way (or not) isn't
> said somewhere, if I see right.
>

I'm not familiar with the TCL side of things, but in the C API "timeout"
installs its own "busy" handler (which sleeps for a moment and then returns
0, or 1 if the timeout has been exceeded).

There can only be one busy handler, so my guess is that the most recent
call to "timeout" or "busy" will determine whether your busy handler or
sqlite's timeout handler gets called.

-Rowan
___
sqlite-users mailing list
sqlite-users@mailinglists.sqlite.org
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users