Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
Each database has its own queue: An update on database A global lock will not block operations on database B. This is under be assigned if the premise that it can be statically determined, i.e., before name of the transaction database is evaluated, which databases will be accessed by not a transaction (see [[#Limitations|below]]). The number of maximum parallel transactions can be adjusted with the [[Options#PARALLEL|PARALLEL]] option.static string:
With * {{VersionCode|8.6for $db in ('db1', 'db2') return db:open($db)}}, locking has been improved* {{Code|doc(doc('test')/reference/text())}}* <code>let $db := 'test' return insert nodes <test/> into db:open($db)</code>
* Jobs without database access will never be locked. Globally locking jobs The functions [[Databases#XML Documents|fn:doc]] and [[Databases#XML Documents|fn:collection]] can now also be executed used to address that are not stored in parallel with non-locking jobsa database.* A However, this may lead to unwanted locks, and you have two options to reduce the number of locks: No database lookups will take place if {{Option|FAIRLOCKWITHDB}} option has been addedis disabled, or if {{Function|Fetch|fetch:xml}} is used instead of [[Databases#XML Documents|fn: By default, read transactions will now be favored, and transactions that access no databases doc]]. You can be evaluated even if consult the query info output (which you find in the [[GUI#Visualizations|Info View]] of the transactions limit has GUI or which you can turn on by setting {{Option|QUERYINFO}} to {{Code|true}}) to find out which databases have been reachedlocked by a query. =XQuery Locks=
==XQuery Locks=={{Mark|Updated with Version 9.4:}} Single lock option for reads and writes.
===Query Options===* A lock string may consist of a single key or multiple keys separated with commas.* Internal locks and XQuery locks can co-exist. No conflicts arise, even if a lock string equals the name of a database that is locked by the transaction manager.* The lock is transformed into a write lock by making the corresponding expression updating.
* The locks are declared as options {{Code|query:read-lock}} and {{Code|query:write-lock}} in the query prolog.* Multiple option declarations can be specified in a module, or values can also be separated with commas in a single declaration.* XQuery locks are in a separate namespace, such that there will be no conflicts with the internal database locks.* Similar to internal locks, write locks block all other operations while read locks allow parallel access.==Annotations==
(declare %basex:~ Write lock for all functions of the module. :('CONFIG')declare option queryfunction config:write-lock "files";read() as xs:~ Config file. :)string {declare variable $config: file := read-text('config.txt')};
declare function configSome explanations:read() { file:read-text($config:file)};</pre>
===Java Modules===* If a query calls the <code>config:read</code> function, a read lock will be acquired for the user-defined {{Code|CONFIG}} lock string before query evaluation.* If <code>config:write</code> is called by a query, a write lock will be applied.* If another query calls <code>config:write</code>, it will be queued until the first query is evaluated.
Locks can also be acquired on [[Java Bindings#Locking|Java functions]] which are imported and invoked from an XQuery expression. It is advisable to explicitly lock Java code whenever it performs sensitive read and write operations.==Pragmas==
==Limitations==Locks can also be declared via pragmas:
Database locking works with all commands unless the glob syntax The write locks is used, such as in enforced via the following command call{{Code|Update|update:output}}.
* {{Code|DROP DB new*}}: drop all databases starting with "new"==Options==
===XQuery===Locks for the functions of a module can also be assigned via option declarations:
Deciding which databases will be accessed by a complex XQuery expression is a non-trivial task. Database detection works for the following types of queries<syntaxhighlight lang="xquery">declare option basex:lock 'CONFIG';
* {{Code|//item}}, read-locking of the database opened by a client* {{Code|docupdate:output(file:write('factbookconfig.xml')}}, read-locking of "factbook"* {{Code|collection('db<config/path/to/docs'>)}}, read-locking of "db"* {{Code|fn:sum(1 to 100)}}, locking nothing at all* {{Code|delete nodes doc('test')<//*[string-length(local-name(.)) syntaxhighlight> 5]}}, write-locking of "test"
All databases will be locked by queries of the following kind:Once again, a write lock is enforced.
* {{Code|for $db in ('db1', 'db2') return doc($db)}}* {{Code|doc(doc('test')/reference/text())}}* <code>let $db := 'test' return insert nodes <test/> into doc($db)</code>=Java Modules==
You Locks can consult the query info output (which you find in the also be acquired on [[GUIJava Bindings#VisualizationsLocking|Info ViewJava functions]] of the GUI or which you can turn on by setting <code>[[Options#QUERYINFO|QUERYINFO]]</are imported and invoked from an XQuery expression. It is advisable to explicitly lock Java code> to {{Code|true}}) to find out which databases have been locked by a querywhenever it performs sensitive read and write operations.
→XQuery Locks
* If an updating transaction comes in, it will be queued and executed after all previous read transaction have been executed.
* Subsequent operations (read or write) will be queued until the updating transaction has completed.
* Jobs without database access will never be locked. Globally locking jobs can now be executed in parallel with non-locking jobs.
* Each database has its own queue: An update on database A will not block operations on database B. This is under the premise that it can be statically determined, i.e., before the transaction is evaluated, which databases will be accessed by a transaction (see [[#Limitations|below]]).
* The number of maximum parallel transactions can be adjusted with the {{Option|PARALLEL}} option.
* By default, read transactions are favored, and transactions that access no databases can be evaluated even if the transactions limit has been reached. This behavior can be changed via the {{Option|FAIRLOCK}} option.
==Limitations==
===Commands===
Database locking works with all commands unless the glob syntax is used, such as in the following command call:
* {{Code|DROP DB new*}}: drop all databases starting with "new"
===XQuery===
Deciding which databases will be accessed by a complex XQuery expression is a non-trivial task. Database detection works for the following types of queries:
* {{Code|//item}}, read-locking of the database opened by a client
* {{Code|doc('factbook')}}, read-locking of "factbook"
* {{Code|collection('db/path/to/docs')}}, read-locking of "db"
* {{Code|fn:sum(1 to 100)}}, locking nothing at all
* {{Code|delete nodes db:open('test')//*[string-length(local-name(.)) > 5]}}, write-locking of "test"
By default, access to external resources (files on hard disk, HTTP requests, ...) is not controlled by the transaction monitor of BaseX. You Custom locks can use custom XQuery locks to do sobe assigned via annotations, pragmas or options:
In the following module, a write lock is declared annotations are used to avoid multiple clients reading or writing to a config file at prevent concurrent write operations on the same timefile:
<pre classsyntaxhighlight lang="brush:xquery">
module namespace config = 'config';
declare %updating %basex:lock('CONFIG') function config:write($configdata as xs:string) { file:write-text($'config:file.txt', $configdata)
};
</syntaxhighlight>
<syntaxhighlight lang===Commands==="xquery">update:output((# basex:lock CONFIG #) { file:write('config.xml', <config/>)})</syntaxhighlight>
=File-System Locks=
=Changelog=
;Version 9.4
* Updated: Single lock option for reads and writes.
;Version 9.1
* Updated: Query lock options were moved from {{Code|query}} to {{Code|basex}} namespace.
;Version 8.6
