Derby
  1. Derby
  2. DERBY-5697

Doc changes to account for correctness fixes for sequences

    Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 10.9.1.0
    • Fix Version/s: 10.9.1.0
    • Component/s: Documentation
    • Labels:
      None
    • Urgency:
      Normal

      Description

      As a result of the correctness fixes made by DERBY-5493 and DERBY-5494, we should adjust the user documentation for sequences. I recommend the following changes:

      1) Reference Guide

      a) Add a section for a new system function. This function lets users observe the instantaneous current value of a sequence generator without having to query SYSSEQUENCES. Querying SYSSEQUENCES didn't actually return the current value, it only returned an upper bound on that value, viz., the end of the chunk of sequence values which had been pre-allocated but not actually used. The new function shows you the very next value which will be returned by a NEXT VALUE FOR clause. Users should never directly query SYSSEQUENCES because that will cause sequence generator concurrency to slow down to a crawl.

      Syntax

      BIGINT SYSCS_UTIL.SYSCS_PEEK_AT_SEQUENCE(IN SCHEMANAME VARCHAR(128), IN SEQUENCENAME VARCHAR(128))

      As with all system functions, schema and object name arguments are case-sensitive.

      Execute privileges

      By default, all users have execute privileges on this function.

      b) SYSSEQUENCES system table

      The Contents description for SYSSEQUENCES.CURRENTVALUE needs to be changed to make a couple points: This is not the actual next value for the sequence generator. That value can be obtained by calling SYSCS_PEEK_AT_SEQUENCE(). SYSSEQUENCES.CURRENTVALUE holds the end of the range of values which have been pre-allocated in order to boost concurrency. Users should not directly query SYSSEQUENCES because that will slow down the performance of sequence generators. Instead, users should call SYSCS_PEEK_AT_SEQUENCE().

      c) derby.language.sequence.preallocator

      The default value of this property has changed from 20 to 100.

      In addition, I think that we should point out that if the database is shut down gracefully, then Derby should not leak unused, preallocated values; they will be thrown away and the sequence generator will pick up where it left off, once the database re-boots. However, if the database comes down ungracefully, then unused, preallocated values will be leaked: when the database comes up again, the sequence generator will skip the unused, preallocated values; this will leave a gap between the last NEXT VALUE FOR (issued before the database came down ungracefully) and the next NEXT VALUE FOR (issued after the database re-boots).

      2) Tuning Guide

      Maybe we should add a small section explaining how to boost the concurrency of sequences:

      a) Don't query SYSSEQUENCES directly. Instead, use SYSCS_PEEK_AT_SEQUENCE().

      b) Adjusting derby.language.sequence.preallocator may boost your concurrency. However, you should pay special attention to bringing down the database gracefully in order to not leak unused, preallocated values. See the Reference Manual section on derby.language.sequence.preallocator.

      1. DERBY-5697.zip
        10 kB
        Kim Haase
      2. DERBY-5697.stat
        0.2 kB
        Kim Haase
      3. DERBY-5697.diff
        13 kB
        Kim Haase

        Issue Links

          Activity

          Hide
          Kim Haase added a comment -

          Rick, when you say "Adjusting derby.language.sequence.preallocator may boost your concurrency" do you mean adjusting it upwards or downwards?

          Thanks!

          Show
          Kim Haase added a comment - Rick, when you say "Adjusting derby.language.sequence.preallocator may boost your concurrency" do you mean adjusting it upwards or downwards? Thanks!
          Hide
          Rick Hillegas added a comment -

          Hi Kim,

          Adjusting derby.language.sequence.preallocator upward may boost your concurrency. At some point, you will have adjusted it high enough that further upward tweaks won't help your application. At that point, your throughput will be constrained by other bottlenecks.

          I don't see how adjusting derby.language.sequence.preallocator downward would ever reduce your concurrency. The reason to lower it would be to leak fewer unused preallocated values. That could be an issue if your application can't guarantee that it will park its databases gracefully before the VM exits. Thanks.

          Show
          Rick Hillegas added a comment - Hi Kim, Adjusting derby.language.sequence.preallocator upward may boost your concurrency. At some point, you will have adjusted it high enough that further upward tweaks won't help your application. At that point, your throughput will be constrained by other bottlenecks. I don't see how adjusting derby.language.sequence.preallocator downward would ever reduce your concurrency. The reason to lower it would be to leak fewer unused preallocated values. That could be an issue if your application can't guarantee that it will park its databases gracefully before the VM exits. Thanks.
          Hide
          Kim Haase added a comment -

          Attaching DERBY-5697.diff, DERBY-5697.stat, and DERBY-5697.zip, with changes as follows:

          M src/tuning/tuningderby.ditamap
          A src/tuning/ctunperfsequences.dita
          M src/ref/refderby.ditamap
          M src/ref/rrefproperpreallocator.dita
          A src/ref/rrefsyscspeeksequence.dita
          M src/ref/rrefsistabssyssequences.dita

          The patch adds a new topic to Tuning Derby and another to the Reference Manual, and modifies the system table and property topics as suggested.

          You'll notice I added some reltable entries to the Reference Manual so suitable links show up on the pages.

          Show
          Kim Haase added a comment - Attaching DERBY-5697 .diff, DERBY-5697 .stat, and DERBY-5697 .zip, with changes as follows: M src/tuning/tuningderby.ditamap A src/tuning/ctunperfsequences.dita M src/ref/refderby.ditamap M src/ref/rrefproperpreallocator.dita A src/ref/rrefsyscspeeksequence.dita M src/ref/rrefsistabssyssequences.dita The patch adds a new topic to Tuning Derby and another to the Reference Manual, and modifies the system table and property topics as suggested. You'll notice I added some reltable entries to the Reference Manual so suitable links show up on the pages.
          Hide
          Rick Hillegas added a comment -

          Thanks, Kim. These changes look good. +1

          Show
          Rick Hillegas added a comment - Thanks, Kim. These changes look good. +1
          Hide
          Kim Haase added a comment -

          Wow, that was quick, Rick – thanks!

          Committed patch DERBY-5697.diff to documentation trunk at revision 1329354.

          Show
          Kim Haase added a comment - Wow, that was quick, Rick – thanks! Committed patch DERBY-5697 .diff to documentation trunk at revision 1329354.
          Hide
          Kim Haase added a comment -

          Changes have appeared in Latest Alpha Manuals.

          Show
          Kim Haase added a comment - Changes have appeared in Latest Alpha Manuals.

            People

            • Assignee:
              Kim Haase
              Reporter:
              Rick Hillegas
            • Votes:
              0 Vote for this issue
              Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development