public class SequenceGenerator
extends java.lang.Object
This is a generic machine for pre-allocating ranges of sequence numbers in order to improve concurrency. The public methods are synchronized and should be brief. The caller of the methods in this class is responsible for updating values on disk when the generator is exhausted or when it needs to allocate a new range of values.
The most used method in this class is getCurrentValueAndAdvance(). This method returns the next number in the range managed by the sequence generator. This method will raise an exception if the sequence generator is exhausted. Otherwise getCurrentValueAndAdvance() hands back a tuple of return values:
( status, currentValue, lastAllocatedValue, numberOfValuesAllocated )
The status field takes the following values:
It may happen that getCurrentValueAndAdvance() tells its caller to allocate a new range of sequence numbers in the system catalog. If the caller successfully allocates a new range, the caller should call allocateNewRange() to tell the generator to update its internal memory of that range.
The peekAtCurrentValue() method is provided so that unused, pre-allocated values can be flushed when the sequence generator is being discarded. The caller updates the catalog with the value returned by peekAtCurrentValue(). The peekAtCurrentValue() method is also called by the syscs_peek_at_sequence() function which users should call rather than try to scan the underlying catalog themselves.
Modifier and Type | Field | Description |
---|---|---|
private boolean |
_CAN_CYCLE |
|
private long |
_currentValue |
|
private long |
_INCREMENT |
|
private boolean |
_isExhausted |
|
private long |
_MAX_VALUE |
|
private long |
_MIN_VALUE |
|
private SequencePreallocator |
_PREALLOCATOR |
|
private long |
_remainingPreallocatedValues |
|
private long |
_RESTART_VALUE |
|
private java.lang.String |
_SCHEMA_NAME |
|
private java.lang.String |
_SEQUENCE_NAME |
|
private boolean |
_STEP_INCREASES |
|
static int |
CVAA_CURRENT_VALUE |
|
static int |
CVAA_LAST_ALLOCATED_VALUE |
|
static int |
CVAA_LENGTH |
|
static int |
CVAA_NUMBER_OF_VALUES_ALLOCATED |
|
static int |
CVAA_STATUS |
|
private static int |
PREALLOCATION_THRESHHOLD |
If pre-allocation drops below this level, then we need to grab another chunk of numbers
|
static int |
RET_ALLOCATE_NEW_VALUES |
|
static int |
RET_I_AM_CONFUSED |
|
static int |
RET_MARK_EXHAUSTED |
|
static int |
RET_OK |
Constructor | Description |
---|---|
SequenceGenerator(java.lang.Long currentValue,
boolean canCycle,
long increment,
long maxValue,
long minValue,
long restartValue,
java.lang.String schemaName,
java.lang.String sequenceName,
SequencePreallocator sequencePreallocator) |
Normal constructor
|
Modifier and Type | Method | Description |
---|---|---|
private void |
advanceValue(long[] retval) |
Advance the sequence generator.
|
void |
allocateNewRange(long expectedCurrentValue,
long numberOfAllocatedValues) |
Allocate a new range.
|
SequenceGenerator |
clone(boolean restart) |
Clone this sequence generator.
|
SequenceGenerator |
clone(java.lang.Long newStartValue) |
Clone this sequence generator.
|
private void |
computeNewAllocation(long oldCurrentValue,
long[] retval) |
Compute the number of values to allocate.
|
private int |
computePreAllocationCount() |
This method returns the number of values to pre-allocate when we
grab a new chunk of values.
|
private long |
computeRemainingValues(long oldCurrentValue) |
Get the number of values remaining until we bump against an endpoint of the legal range of values.
|
long[] |
getCurrentValueAndAdvance() |
Get the next sequence number managed by this generator and advance the number.
|
java.lang.String |
getName() |
Get the name of this sequence generator.
|
java.lang.String |
getSchemaName() |
Get the name of the schema of this sequence generator.
|
private void |
markExhausted(long[] retval) |
Mark the generator as exhausted.
|
private boolean |
overflowed(long originalValue,
long incrementedValue) |
Return true if an overflow/underflow occurred.
|
java.lang.Long |
peekAtCurrentValue() |
Peek at the current value of the sequence generator without advancing the
generator.
|
private static final int PREALLOCATION_THRESHHOLD
public static final int RET_I_AM_CONFUSED
public static final int RET_OK
public static final int RET_MARK_EXHAUSTED
public static final int RET_ALLOCATE_NEW_VALUES
public static final int CVAA_STATUS
public static final int CVAA_CURRENT_VALUE
public static final int CVAA_LAST_ALLOCATED_VALUE
public static final int CVAA_NUMBER_OF_VALUES_ALLOCATED
public static final int CVAA_LENGTH
private final boolean _CAN_CYCLE
private final boolean _STEP_INCREASES
private final long _INCREMENT
private final long _MAX_VALUE
private final long _MIN_VALUE
private final long _RESTART_VALUE
private final java.lang.String _SCHEMA_NAME
private final java.lang.String _SEQUENCE_NAME
private final SequencePreallocator _PREALLOCATOR
private boolean _isExhausted
private long _currentValue
private long _remainingPreallocatedValues
public SequenceGenerator(java.lang.Long currentValue, boolean canCycle, long increment, long maxValue, long minValue, long restartValue, java.lang.String schemaName, java.lang.String sequenceName, SequencePreallocator sequencePreallocator)
public SequenceGenerator clone(boolean restart)
Clone this sequence generator. This method supports the special bulk-insert optimization in InsertResultSet.
restart
- True if the clone should be reset to start at the beginning instead of at the current value.public SequenceGenerator clone(java.lang.Long newStartValue)
Clone this sequence generator. This method supports the special bulk-insert optimization in InsertResultSet.
newStartValue
- New value to start with.public java.lang.String getSchemaName()
Get the name of the schema of this sequence generator. Technically, this doesn't need to be synchronized. But it is simpler to just maintain a rule that all public methods should be synchronized.
public java.lang.String getName()
Get the name of this sequence generator. Technically, this doesn't need to be synchronized. But it is simpler to just maintain a rule that all public methods should be synchronized.
public void allocateNewRange(long expectedCurrentValue, long numberOfAllocatedValues)
Allocate a new range. Is a NOP if the current value is not what we expected. See the class header comment for more information on how this method is used.
public java.lang.Long peekAtCurrentValue()
Peek at the current value of the sequence generator without advancing the generator. Returns null if the generator is exhausted.
public long[] getCurrentValueAndAdvance() throws StandardException
Get the next sequence number managed by this generator and advance the number. Could raise an exception if the legal range is exhausted and wrap-around is not allowed--that is, if NO CYCLE was specified when the sequence was defined. See the class header comment for a description of how this method operates.
StandardException
private void advanceValue(long[] retval) throws StandardException
Advance the sequence generator. Pre-allocate a range of new values if necessary.
retval
- Array of return values to fill in: see CVAA_* constantsStandardException
private void markExhausted(long[] retval)
Mark the generator as exhausted.
private boolean overflowed(long originalValue, long incrementedValue)
Return true if an overflow/underflow occurred. This happens if the originalValue and incrementedValue have opposite sign. Overflow also occurs if the incrementedValue falls outside the range of the sequence.
private void computeNewAllocation(long oldCurrentValue, long[] retval) throws StandardException
Compute the number of values to allocate. The range may wrap around.
oldCurrentValue
- INPUT Used to compute how many values need to be allocatedretval
- OUTPUT Array of values to fill in (see CVAA_* constants)StandardException
- if any error occurs.private long computeRemainingValues(long oldCurrentValue)
Get the number of values remaining until we bump against an endpoint of the legal range of values. This is a positive number and so may understate the number of remaining values if the datatype is BIGINT.
private int computePreAllocationCount()
This method returns the number of values to pre-allocate when we grab a new chunk of values. This is a bit of defensive coding to cover the case when the sequence's parameters are absurdly large.
Apache Derby V10.14 Internals - Copyright © 2004,2018 The Apache Software Foundation. All Rights Reserved.