db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From chaa...@apache.org
Subject svn commit: r1329354 - in /db/derby/docs/trunk/src: ref/refderby.ditamap ref/rrefproperpreallocator.dita ref/rrefsistabssyssequences.dita ref/rrefsyscspeeksequence.dita tuning/ctunperfsequences.dita tuning/tuningderby.ditamap
Date Mon, 23 Apr 2012 17:53:52 GMT
Author: chaase3
Date: Mon Apr 23 17:53:52 2012
New Revision: 1329354

URL: http://svn.apache.org/viewvc?rev=1329354&view=rev
Log:
DERBY-5697  Doc changes to account for correctness fixes for sequences

Added a new topic to Tuning Derby; added a new topic to Reference Manual and modified two
others.

Patch: DERBY-5697.diff

Added:
    db/derby/docs/trunk/src/ref/rrefsyscspeeksequence.dita   (with props)
    db/derby/docs/trunk/src/tuning/ctunperfsequences.dita   (with props)
Modified:
    db/derby/docs/trunk/src/ref/refderby.ditamap
    db/derby/docs/trunk/src/ref/rrefproperpreallocator.dita
    db/derby/docs/trunk/src/ref/rrefsistabssyssequences.dita
    db/derby/docs/trunk/src/tuning/tuningderby.ditamap

Modified: db/derby/docs/trunk/src/ref/refderby.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/refderby.ditamap?rev=1329354&r1=1329353&r2=1329354&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/refderby.ditamap (original)
+++ db/derby/docs/trunk/src/ref/refderby.ditamap Mon Apr 23 17:53:52 2012
@@ -33,6 +33,61 @@ limitations under the License.
 <reltable>
 <relrow>
 <relcell>
+<topicref href="rrefsyscspeeksequence.dita" navtitle="SYSCS_UTIL.SYSCS_PEEK_AT_SEQUENCE
system function"></topicref>
+</relcell>
+<relcell>
+<topicref href="rrefsqljcreatesequence.dita" navtitle="CREATE SEQUENCE statement"></topicref>
+<topicref href="rrefsqljdropsequence.dita" navtitle="DROP SEQUENCE statement"></topicref>
+<topicref href="rrefsistabssyssequences.dita" navtitle="SYSSEQUENCES system table"></topicref>
+<topicref href="rrefproperpreallocator.dita" navtitle="derby.language.sequence.preallocator"></topicref>
+</relcell>
+</relrow>
+<relrow>
+<relcell>
+<topicref href="rrefsqljcreatesequence.dita" navtitle="CREATE SEQUENCE statement"></topicref>
+</relcell>
+<relcell>
+<topicref href="rrefsqljdropsequence.dita" navtitle="DROP SEQUENCE statement"></topicref>
+<topicref href="rrefsyscspeeksequence.dita" navtitle="SYSCS_UTIL.SYSCS_PEEK_AT_SEQUENCE
system function"></topicref>
+<topicref href="rrefsistabssyssequences.dita" navtitle="SYSSEQUENCES system table"></topicref>
+<topicref href="rrefproperpreallocator.dita" navtitle="derby.language.sequence.preallocator"></topicref>
+</relcell>
+</relrow>
+<relrow>
+<relcell>
+<topicref href="rrefsqljdropsequence.dita" navtitle="DROP SEQUENCE statement"></topicref>
+</relcell>
+<relcell>
+<topicref href="rrefsqljcreatesequence.dita" navtitle="CREATE SEQUENCE statement"></topicref>
+<topicref href="rrefsyscspeeksequence.dita" navtitle="SYSCS_UTIL.SYSCS_PEEK_AT_SEQUENCE
system function"></topicref>
+<topicref href="rrefsistabssyssequences.dita" navtitle="SYSSEQUENCES system table"></topicref>
+<topicref href="rrefproperpreallocator.dita" navtitle="derby.language.sequence.preallocator"></topicref>
+</relcell>
+</relrow>
+<relrow>
+<relcell>
+<topicref href="rrefsistabssyssequences.dita" navtitle="SYSSEQUENCES system table"></topicref>
+</relcell>
+<relcell>
+<topicref href="rrefsqljcreatesequence.dita" navtitle="CREATE SEQUENCE statement"></topicref>
+<topicref href="rrefsqljdropsequence.dita" navtitle="DROP SEQUENCE statement"></topicref>
+<topicref href="rrefsyscspeeksequence.dita" navtitle="SYSCS_UTIL.SYSCS_PEEK_AT_SEQUENCE
system function"></topicref>
+<topicref href="rrefproperpreallocator.dita" navtitle="derby.language.sequence.preallocator"></topicref>
+</relcell>
+</relrow>
+<relrow>
+<relcell>
+<topicref href="rrefproperpreallocator.dita" navtitle="derby.language.sequence.preallocator"></topicref>
+</relcell>
+<relcell>
+<topicref href="rrefsqljcreatesequence.dita" navtitle="CREATE SEQUENCE statement"></topicref>
+<topicref href="rrefsqljdropsequence.dita" navtitle="DROP SEQUENCE statement"></topicref>
+<topicref href="rrefsyscspeeksequence.dita" navtitle="SYSCS_UTIL.SYSCS_PEEK_AT_SEQUENCE
system function"></topicref>
+<topicref href="rrefsistabssyssequences.dita" navtitle="SYSSEQUENCES system table"></topicref>
+</relcell>
+</relrow>
+<relrow>
+<relcell>
 <topicref href="rrefcase.dita" navtitle="CASE expression"></topicref>
 </relcell>
 <relcell>
@@ -394,6 +449,7 @@ limitations under the License.
 </topicref>
 <topicref href="rref_syscs_get_xplain_mode.dita" navtitle="SYSCS_UTIL.SYSCS_GET_XPLAIN_MODE
system function"></topicref>
 <topicref href="rref_syscs_get_xplain_schema.dita" navtitle="SYSCS_UTIL.SYSCS_GET_XPLAIN_SCHEMA
system function"></topicref>
+<topicref href="rrefsyscspeeksequence.dita" navtitle="SYSCS_UTIL.SYSCS_PEEK_AT_SEQUENCE
system function"></topicref>
 </topicref>
 <topicref href="crefsqlbuiltinsystemprocedures.dita" navtitle="Built-in system procedures">
 <!--(Laura - March 2007) The topics in this section are intentionally not listed alphabetical
order. They are listed by group of information. For example, the COMPRESS and INPLACE_COMPRESS
topics are listed together; the IMPORT and EXPORT topics are listed together.-->

Modified: db/derby/docs/trunk/src/ref/rrefproperpreallocator.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefproperpreallocator.dita?rev=1329354&r1=1329353&r2=1329354&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefproperpreallocator.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefproperpreallocator.dita Mon Apr 23 17:53:52 2012
@@ -27,6 +27,15 @@ limitations under the License.
 </prolog><refbody>
 <section><title>Function</title>
 <p>Specifies how many values to preallocate for sequences.</p>
+<p>If the database is shut down in an orderly fashion,
+<ph conref="../conrefs.dita#prod/productshortname"></ph> will not leak unused
+preallocated values. Instead, any unused values will be thrown away, and the
+sequence generator will continue where it left off once the database reboots.
+However, if the database exits unexpectedly, the sequence generator will
+skip the unused preallocated values when the database comes up again. This will
+leave a gap between the last NEXT VALUE FOR (issued before the database exited
+unexpectedly) and the next NEXT VALUE FOR (issued after the database
+reboots).</p>
 </section>
 <refsyn><title>Syntax</title>
 <codeblock><b>derby.language.sequence.preallocator=<i>number</i></b></codeblock>
@@ -37,8 +46,8 @@ or
 <p>
 If set to a positive number, that is the number of values which
 <ph conref="../conrefs.dita#prod/productshortname"></ph>
-preallocates for each sequence.
-</p>
+preallocates for each sequence. A higher value may improve the concurrency of
+sequences.</p>
 <p>
 If set to a class name, that class must implement
 <i>org.apache.derby.catalog.SequencePreallocator</i>. The class
@@ -47,12 +56,12 @@ customizes the size of the preallocation
 </p>
 </refsyn>
 <section><title>Default</title>
-<p>20</p>
-<p>By default, <ph conref="../conrefs.dita#prod/productshortname"></ph>
preallocates 20
-values for each sequence.</p>
+<p>100</p>
+<p>By default, <ph conref="../conrefs.dita#prod/productshortname"></ph>
+preallocates 100 values for each sequence.</p>
 </section>
 <example><title>Example</title>
-<codeblock><b>derby.language.sequence.preallocator=50</b></codeblock>
+<codeblock><b>derby.language.sequence.preallocator=125</b></codeblock>
 </example>
 <section><title>Scope</title>
 <p>

Modified: db/derby/docs/trunk/src/ref/rrefsistabssyssequences.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsistabssyssequences.dita?rev=1329354&r1=1329353&r2=1329354&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsistabssyssequences.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefsistabssyssequences.dita Mon Apr 23 17:53:52 2012
@@ -31,6 +31,10 @@ database.</shortdesc>
 </metadata></prolog>
 <refbody>
 <section>
+<p><note>Users should not directly query the SYSSEQUENCES table, because that
+will slow down the performance of sequence generators. Instead, users should
+call the
+<xref href="rrefsyscspeeksequence.dita#rrefsyscspeeksequence"></xref>.</note></p>
 <p>The following table shows the contents of the SYSSEQUENCES system table.</p>
 <table>
 <title>SYSSEQUENCES system table</title>
@@ -90,7 +94,11 @@ nullability, type name, and storage type
 <entry colname="2">BIGINT</entry>
 <entry colname="3">20</entry>
 <entry colname="4">true</entry>
-<entry colname="5">The current value of the sequence generator. The initial
+<entry colname="5">The current value of the sequence generator. This is not the
+actual next value for the sequence generator. That value can be obtained by
+calling the system function SYSCS_UTIL.SYSCS_PEEK_AT_SEQUENCE.
+SYSSEQUENCES.CURRENTVALUE holds the end of the range of values which have been
+preallocated in order to boost concurrency. The initial
 value of this column is STARTVALUE. This column is NULL only if the sequence
 generator is exhausted and cannot issue any more numbers.</entry>
 </row>

Added: db/derby/docs/trunk/src/ref/rrefsyscspeeksequence.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsyscspeeksequence.dita?rev=1329354&view=auto
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsyscspeeksequence.dita (added)
+++ db/derby/docs/trunk/src/ref/rrefsyscspeeksequence.dita Mon Apr 23 17:53:52 2012
@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
+ "../dtd/reference.dtd">
+<reference id="rrefsyscspeeksequence" xml:lang="en-us">
+<title>SYSCS_UTIL.SYSCS_PEEK_AT_SEQUENCE system function</title>
+<refbody>
+<section><p>The <codeph>SYSCS_UTIL.SYSCS_PEEK_AT_SEQUENCE</codeph>
function
+allows users to observe the instantaneous current value of a sequence generator
+without having to query the
+<xref href="rrefsistabssyssequences.dita#rrefsistabssyssequences"></xref>.
+Querying the SYSSEQUENCES table does not actually return the current value; it
+only returns an upper bound on that value, that is, the end of the chunk of
+sequence values which has been preallocated but not actually used. The
+<codeph>SYSCS_UTIL.SYSCS_PEEK_AT_SEQUENCE</codeph> function shows you the very
+next value which will be returned by a NEXT VALUE FOR clause. Users should never
+directly query the SYSSEQUENCES table, because that will cause sequence
+generator concurrency to slow drastically.</p></section>
+<refsyn><title>Syntax</title>
+<codeblock>BIGINT SYSCS_UTIL.SYSCS_PEEK_AT_SEQUENCE(IN SCHEMANAME VARCHAR(128),
+IN SEQUENCENAME VARCHAR(128))</codeblock>
+<p>As with all system functions, schema and object name arguments are
+case-sensitive.</p>
+</refsyn>
+<section><title>Execute privileges</title>
+<p>By default, all users have execute privileges on this function.</p>
+</section>
+<example><title>Example</title>
+<codeblock>VALUES SYSCS_UTIL.SYSCS_PEEK_AT_SEQUENCE('APP', 'order_entry_id');</codeblock>
+</example>
+</refbody>
+</reference>

Propchange: db/derby/docs/trunk/src/ref/rrefsyscspeeksequence.dita
------------------------------------------------------------------------------
    svn:eol-style = native

Added: db/derby/docs/trunk/src/tuning/ctunperfsequences.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunperfsequences.dita?rev=1329354&view=auto
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunperfsequences.dita (added)
+++ db/derby/docs/trunk/src/tuning/ctunperfsequences.dita Mon Apr 23 17:53:52 2012
@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="utf-8"?>
+ 
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
+ "../dtd/concept.dtd">
+<!-- 
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at      
+
+   http://www.apache.org/licenses/LICENSE-2.0  
+
+Unless required by applicable law or agreed to in writing, software  
+distributed under the License is distributed on an "AS IS" BASIS,  
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  
+See the License for the specific language governing permissions and  
+limitations under the License.
+-->
+<concept id="ctunperfsequences" xml:lang="en-us">
+<title>Increase the concurrency of sequences</title>
+<prolog><metadata><keywords>
+<indexterm>sequences<indexterm>concurrency</indexterm></indexterm>
+<indexterm>concurrency<indexterm>sequences</indexterm></indexterm>
+</keywords></metadata></prolog>
+<conbody>
+<p>If you use a sequence generator (created with the CREATE SEQUENCE statement),
+you can increase its concurrency by doing the following:</p>
+<ul>
+<li>Do not query the SYSSEQUENCES system table directly. Instead, use the
+SYSCS_UTIL.SYSCS_PEEK_AT_SEQUENCE system function to obtain the current value
+of a sequence generator.</li>
+<li>Specifying a higher value for the
+<i>derby.language.sequence.preallocator</i> property may increase your
+concurrency. However, you should pay special attention to bringing down the
+database in an orderly fashion in order to not leak unused preallocated
+values. (See also
+<xref href="ctunperf17936.dita#ctunperf17936"></xref>.)</li>
+</ul>
+<p>See the <ph conref="../conrefs.dita#pub/citref"></ph> for more information
+about the CREATE SEQUENCE statement, the SYSSEQUENCES system table, the
+SYSCS_UTIL.SYSCS_PEEK_AT_SEQUENCE system function, and the
+<i>derby.language.sequence.preallocator</i> property.</p> 
+</conbody>
+</concept>

Propchange: db/derby/docs/trunk/src/tuning/ctunperfsequences.dita
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: db/derby/docs/trunk/src/tuning/tuningderby.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/tuningderby.ditamap?rev=1329354&r1=1329353&r2=1329354&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/tuningderby.ditamap (original)
+++ db/derby/docs/trunk/src/tuning/tuningderby.ditamap Mon Apr 23 17:53:52 2012
@@ -66,6 +66,8 @@ toc="no"></topicref>
 </topicref>
 <topicref href="ctunperfinmemdb.dita" navtitle="Configure Derby to use an in-memory database">
 </topicref>
+<topicref href="ctunperfsequences.dita" navtitle="Increase the concurrency of sequences">
+</topicref>
 </topicref>
 <topicref collection-type="family" href="ctunperf31086.dita" navtitle="More tips">
 <topicref href="ctunperf17936.dita" navtitle="Shut down the system properly">



Mime
View raw message