docs/_docs/data-structures/id-generator.adoc

// 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.
= Distributed ID Generator

== Overview

The distributed atomic sequence provided by the `IgniteCacheAtomicSequence` interface is similar to the distributed atomic long,
but its value can only go up. It also supports reserving a range of values to avoid costly network trips or cluster updates
every time a sequence must provide a next value. That is, when you perform `incrementAndGet()` (or any other atomic operation)
on an atomic sequence, the data structure reserves ahead a range of values, which are guaranteed to be unique across the
cluster for this sequence instance.

As a result, the atomic sequence is a suitable and efficient data structure for the implementation of a
distributed ID generator. For instance, such a generator can be used to produce unique primary keys across the whole cluster.

Here is an example of how atomic sequence can be created:

[tabs]
--
tab:Java[]
[source, java]
----
Ignite ignite = Ignition.ignite();

IgniteAtomicSequence seq = ignite.atomicSequence(
    "seqName", // Sequence name.
    0,       // Initial value for sequence.
    true     // Create if it does not exist.
);
----
--

Below is a simple usage example:

[tabs]
--
tab:Java[]
[source, java]
----
Ignite ignite = Ignition.ignite();

// Initialize atomic sequence.
final IgniteAtomicSequence seq = ignite.atomicSequence("seqName", 0, true);

// Increment atomic sequence.
for (int i = 0; i < 20; i++) {
  long currentValue = seq.get();
  long newValue = seq.incrementAndGet();

  ...
}
----
--

== Sequence Reserve Size

The key parameter of `IgniteAtomicSequence` is `atomicSequenceReserveSize` which is the number of sequence values reserved
per node. When a node tries to obtain an instance of `IgniteAtomicSequence`, a number of sequence values will be reserved
for that node and consequent increments of sequence will happen locally without communication with other nodes, until
the next reservation has to be made.

The default value for `atomicSequenceReserveSize` is `1000`. This default setting can be changed by modifying the
`atomicSequenceReserveSize` property of `AtomicConfiguration`.