Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
Each database has its own queue==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*}}: An update on database A drop all databases starting with "new" ===XQuery=== Deciding which databases will not block operations on database Bbe accessed by a complex XQuery expression is a non-trivial task. This is under Database detection works for the following types of queries: * {{Code|//item}}, read-locking of the premise that it can be statically determineddatabase 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)}}, i.elocking nothing at all* {{Code|delete nodes db:open('test')//*[string-length(local-name(.)) > 5]}}, before write-locking of "test" A global lock will be assigned if the name of the transaction database is evaluatednot a static string: * {{Code|for $db in ('db1', which databases will be accessed by a transaction 'db2') return db:open($db)}}* {{Code|doc(doc('test')/reference/text())}}* <code>let $db := 'test' return insert nodes <test/> into db:open(see $db)</code> The functions [[Databases#XML Documents|fn:doc]] and [[Databases#LimitationsXML Documents|belowfn:collection]])can also be used to address that are not stored in a database. The However, this may lead to unwanted locks, and you have two options to reduce the number of maximum parallel transactions can be adjusted with the locks: No database lookups will take place if {{Option|WITHDB}} option is disabled, or if {{Function|Fetch|fetch:xml}} is used instead of [[OptionsDatabases#PARALLELXML Documents|PARALLELfn:doc]] option.
With You can consult the query info output (which you find in the [[GUI#Visualizations|Info View]] of the GUI or which you can turn on by setting {{Option|QUERYINFO}} to {{VersionCode|8.6true}}, locking has ) to find out which databases have been improved:locked by a query.
* A {{Option|FAIRLOCK}} option has been added: By default, read transactions will now be favored, and transactions that access no databases can be evaluated even if the transactions limit has been reached.* A globally locking job can now be executed in parallel with a non-locking job.=XQuery Locks=
==External Side Effects=={{Mark|Updated with Version 9.4:}} Single lock option for reads and writes.
Access By default, access to external resources (files on hard disk, HTTP requests, ...) is not controlled by the transaction monitor of BaseX unless specified by the user.Custom locks can be assigned via annotations, pragmas or options:
===* A lock string may consist of a single key or multiple keys separated with commas.* Internal locks and XQuery Locking Options===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.
Custom locks can be acquired by setting the BaseX-specific XQuery options {{Code|query:read-lock}} and {{Code|query:write-lock}}. Multiple option declarations may occur in the prolog of a query, but multiple values can also be separated with commas in a single declaration. These locks are in another namespace than the database names: the lock value {{Code|factbook}} will not lock a database named factbook.==Annotations==
These option declarations will put read locks on ''foo''In the following module, ''bar'' and ''batz'' and a lock annotations are used to prevent concurrent write lock operations on ''quix''the same file:
===Java Modules===declare %basex:lock('CONFIG') function config:read() as xs:string { file:read-text('config.txt')};
Locks can also declare %updating %basex:lock('CONFIG') function config:write($data as xs:string) { file:write-text('config.txt', $data)};</syntaxhighlight> Some explanations: * If a query calls the <code>config:read</code> function, a read lock will be acquired on [[Java Bindings#Lockingfor the user-defined {{Code|Java functions]] which are imported and invoked from an XQuery expressionCONFIG}} lock string before query evaluation. It * If <code>config:write</code> is advisable to explicitly called by a query, a write lock Java will be applied.* If another query calls <code whenever >config:write</code>, it performs sensitive read and write operationswill be queued until the first query is evaluated. ==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.
<pre classsyntaxhighlight lang="brush:xquery">declare option query:read-lock "foo,bar"module namespace config = 'config';declare option query:read-lock "batz";declare option query:write-lock "quix";</pre>
<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
