Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
By default, access to external resources (files on hard disk, HTTP requests, {{Mark|Updated with Version 9.4:}} Single lock option for reads and writes..) is not controlled by the transaction monitor of BaseX. You can use custom XQuery locks to do so:
===OptionsBy default, Pragmasaccess to external resources (files on hard disk, Annotations===HTTP requests, ...) is not controlled by the transaction monitor of BaseX. Custom locks can be assigned via annotations, pragmas or options:
{{Mark|Introduced * A lock string may consist of a single key or multiple keys separated with Version 9commas.1}}: * Internal locks via pragmas and function annotationsXQuery 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.
* You can declare custom read and write locks via options, pragmas or function annotations.* The value of the lock may contain one or multiple lock keys (separated with commas). The default value is an empty string.* Similar to the internal database locks, write locks block all other operations while read locks allow parallel access.* The internal locks and XQuery locks can co-exist (there will be no conflicts, even if your lock string equals the name of a database that will be locked by the transaction manager).==Annotations==
Local locks Locks can also be declared via pragmas:
Locks for The write locks is enforced via the functions of a module can be assigned via option declarations{{Code|Update|update:output}}.
<pre class="brush:xquery">declare option basex:write-lock 'CONFIG';file:write('config.xml', <config/>)</pre>=Options==
Before {{Version|9.1}}, locks were declared in Locks for the {{Code|query}} namespace.functions of a module can also be assigned via option declarations:
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 update:output(file:write operations('config.xml', <config/>))</syntaxhighlight>
==Limitations==Once again, a write lock is enforced.
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 Locks can also 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 doc('test')//*[string-length(local-name(.)) > 5]}}, write-locking of "test" All databases will be locked by queries of the following kind: * {{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> You can consult the query info output (which you find in the acquired on [[GUIJava Bindings#VisualizationsLocking|Info ViewJava functions]] of the GUI or which you can turn on by setting {{Option|QUERYINFO}} are imported and invoked from an XQuery expression. It is advisable to {{Code|true}}) to find out which databases have been locked by a queryexplicitly lock Java code whenever it performs sensitive read and write operations.
→XQuery Locks
* 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" A global lock will be assigned if the name of the database is not a static string: * {{Code|for $db in ('db1', 'db2') return db:open($db)}}* {{Code|doc(doc('test')/reference/text())}}* <code>let $db := 'test' return insert nodes <test/> into db:open($db)</code> The functions [[Databases#XML Documents|fn:doc]] and [[Databases#XML Documents|fn:collection]] can also be used to address that are not stored in a database. 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|WITHDB}} option is disabled, or if {{Function|Fetch|fetch:xml}} is used instead of [[Databases#XML Documents|fn:doc]]. 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 {{Code|true}}) to find out which databases have been locked by a query. =XQuery Locks==
In the following module, lock annotations are used to prevent concurrent write operations on the same file:
<pre classsyntaxhighlight lang="brush:xquery">
module namespace config = 'config';
declare %basex:read-lock('CONFIG') function config:read() as xs:string {
file:read-text('config.txt')
};
declare %updating %basex:write-lock('CONFIG') function config:write($dataas xs:string) {
file:write-text('config.txt', $data)
};
</presyntaxhighlight>
Some explanations:
* 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 on this lock string will be set for this queryapplied.* If a another query calls <code>config:write</code>, it will be queued until there is no running query left that has {{Code|CONFIG}} locked.* If the writing first query will be is evaluated, all other queries that will set a {{Code|CONFIG}} lock (reading or writing) will have to wait. ==Pragmas==
<pre classsyntaxhighlight lang="brush:xquery">update:output((# basex:write-lock CONFIG #) {
file:write('config.xml', <config/>)
})</presyntaxhighlight>
<syntaxhighlight lang===Java Modules==="xquery">declare option basex:lock 'CONFIG';
===Commands=Java Modules==
=File-System Locks=
=Changelog=
;Version 9.4
* Updated: Single lock option for reads and writes.
;Version 9.1
