[doc-en] master: SQLite3::busyTimeout(): explain how the busy handler works (#5988)

Author: qodelicious (qodelicious) Committer: GitHub (web-flow) Pusher: lacatoire Date: 2026-10-21T13:33:35+02:00 Commit: https://github.com/php/doc-en/commit/b57e4540345a84d3f82ffd0e84dc40d3f9c35241 Raw diff: https://github.com/php/doc-en/commit/b57e4540345a84d3f82ffd0e84dc40d3f9c35241.diff SQLite3::busyTimeout(): explain how the busy handler works (#5988) * SQLite3::busyTimeout(): explain how the busy handler works * Cover the return value and what a timeout failure looks like Also switch the changed paragraphs to simpara. * Use exceptionname for SQLite3Exception Changed paths: M reference/sqlite3/sqlite3/busyTimeout.xml Diff: diff --git a/reference/sqlite3/sqlite3/busyTimeout.xml b/reference/sqlite3/sqlite3/busyTimeout.xml index e28fc5585b2c..6401fafb409e 100644 --- a/reference/sqlite3/sqlite3/busyTimeout.xml +++ b/reference/sqlite3/sqlite3/busyTimeout.xml @@ -15,6 +15,25 @@ <para> Sets a busy handler that will sleep until the database is not locked or the timeout is reached. </para> + <simpara> + The busy handler is built into SQLite, so no callback has to be provided. + When a statement finds the database locked by another connection, SQLite + keeps retrying for up to <parameter>milliseconds</parameter>. If the + database is still locked after that, the statement fails with a + <literal>database is locked</literal> error (<literal>SQLITE_BUSY</literal>). + </simpara> + <simpara> + How that failure shows up depends on + <methodname>SQLite3::enableExceptions</methodname>. With exceptions enabled, + an <exceptionname>SQLite3Exception</exceptionname> is thrown. Otherwise an + <constant>E_WARNING</constant> is raised and the method that ran the + statement, such as <methodname>SQLite3::exec</methodname> or + <methodname>SQLite3::query</methodname>, returns &false;. + </simpara> + <simpara> + By default no busy handler is set, so a statement fails right away if the + database is locked. + </simpara> </refsect1> <refsect1 role="parameters"> @@ -24,10 +43,11 @@ <varlistentry> <term><parameter>milliseconds</parameter></term> <listitem> - <para> - The milliseconds to sleep. Setting this value to a value less than - or equal to zero, will turn off an already set timeout handler. - </para> + <simpara> + The maximum number of milliseconds to wait for a lock. Setting this + value to a value less than or equal to zero, will turn off an already + set timeout handler. + </simpara> </listitem> </varlistentry> </variablelist> @@ -36,9 +56,11 @@ <refsect1 role="returnvalues"> &reftitle.returnvalues; - <para> - Returns &true; on success, &return.falseforfailure;. - </para> + <simpara> + Returns &true; if the busy timeout was set, &return.falseforfailure;. + The return value only tells whether the timeout was set. It does not mean + that later statements will get the lock in time. + </simpara> </refsect1> </refentry>