diff --git a/doc/src/sgml/ref/create_sequence.sgml b/doc/src/sgml/ref/create_sequence.sgml
index 4916b8b649b4dbbd7f975da8ebf3c9a491eb8dbc..718037785c2972e3259d7a55586900f582f4d079 100644
--- a/doc/src/sgml/ref/create_sequence.sgml
+++ b/doc/src/sgml/ref/create_sequence.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_sequence.sgml,v 1.14 2000/10/05 19:48:17 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_sequence.sgml,v 1.15 2000/12/08 20:06:58 tgl Exp $
Postgres documentation
-->
@@ -77,9 +77,9 @@ CREATE SEQUENCE <replaceable class="parameter">seqname</replaceable> [ INCREMENT
<term><replaceable class="parameter">maxvalue</replaceable></term>
<listitem>
<para>
- Use the optional clause <option>MAXVALUE
- <replaceable class="parameter">maxvalue</replaceable></option> to
- determine the maximum
+ The optional clause <option>MAXVALUE
+ <replaceable class="parameter">maxvalue</replaceable></option>
+ determines the maximum
value for the sequence. The defaults are 2147483647 and -1 for
ascending and descending sequences, respectively.
</para>
@@ -120,15 +120,15 @@ CREATE SEQUENCE <replaceable class="parameter">seqname</replaceable> [ INCREMENT
<listitem>
<para>
The optional CYCLE keyword may be used to enable the sequence
- to continue when the
+ to wrap around when the
<replaceable class="parameter">maxvalue</replaceable> or
<replaceable class="parameter">minvalue</replaceable> has been
reached by
an ascending or descending sequence respectively. If the limit is
- reached, the next number generated will be whatever the
+ reached, the next number generated will be the
<replaceable class="parameter">minvalue</replaceable> or
- <replaceable class="parameter">maxvalue</replaceable> is,
- as appropriate.
+ <replaceable class="parameter">maxvalue</replaceable>,
+ respectively.
</para>
</listitem>
</varlistentry>
@@ -192,7 +192,7 @@ ERROR: DefineSequence: MINVALUE (<replaceable class="parameter">min</replaceabl
</computeroutput></term>
<listitem>
<para>
- If the minimum and maximum values are inconsistant.
+ If the minimum and maximum values are inconsistent.
</para>
</listitem>
</varlistentry>
@@ -213,24 +213,24 @@ ERROR: DefineSequence: MINVALUE (<replaceable class="parameter">min</replaceabl
into the current data base. This involves creating and initializing a
new single-row
table with the name <replaceable class="parameter">seqname</replaceable>.
- The generator will be "owned" by the user issuing the command.
+ The generator will be owned by the user issuing the command.
</para>
<para>
After a sequence is created, you may use the function
- <function>nextval(<replaceable class="parameter">seqname</replaceable>)</function>
+ <function>nextval('<replaceable class="parameter">seqname</replaceable>')</function>
to get a new number from the sequence.
The function
<function>currval('<replaceable class="parameter">seqname</replaceable>')</function>
may be used to determine the number returned by the last call to
- <function>nextval(<replaceable class="parameter">seqname</replaceable>)</function>
+ <function>nextval('<replaceable class="parameter">seqname</replaceable>')</function>
for the specified sequence in the current session.
The function
<function>setval('<replaceable class="parameter">seqname</replaceable>',
<replaceable class="parameter">newvalue</replaceable>)</function>
may be used to set the current value of the specified sequence.
The next call to
- <function>nextval(<replaceable class="parameter">seqname</replaceable>)</function>
+ <function>nextval('<replaceable class="parameter">seqname</replaceable>')</function>
will return the given value plus the sequence increment.
</para>
@@ -241,7 +241,7 @@ ERROR: DefineSequence: MINVALUE (<replaceable class="parameter">min</replaceabl
SELECT * FROM <replaceable>seqname</replaceable>;
</programlisting>
- to get the parameters of a sequence.
+ to examine the parameters of a sequence.
As an alternative to fetching the
parameters from the original definition as above, you can use
@@ -254,8 +254,13 @@ SELECT last_value FROM <replaceable>seqname</replaceable>;
</para>
<para>
- Low-level locking is used to enable multiple simultaneous
- calls to a generator.
+ To avoid blocking of concurrent transactions
+ that obtain numbers from the same sequence, a nextval operation
+ is never rolled back; that is, once a value has been fetched it is
+ considered used, even if the transaction that did the nextval later
+ aborts. This means that aborted transactions may leave unused "holes"
+ in the sequence of assigned values. setval operations are never
+ rolled back, either.
</para>
<caution>
@@ -279,6 +284,9 @@ SELECT last_value FROM <replaceable>seqname</replaceable>;
are all distinct, not that they are generated purely sequentially.
Also, last_value will reflect the latest value reserved by any backend,
whether or not it has yet been returned by nextval.
+ Another consideration is that a setval executed on such a sequence
+ will not be noticed by other backends until they have used up any
+ preallocated values they have cached.
</para>
</caution>
@@ -293,7 +301,7 @@ SELECT last_value FROM <replaceable>seqname</replaceable>;
Use <command>DROP SEQUENCE</command> to remove a sequence.
</para>
<para>
- Each backend uses its own cache to store allocated numbers.
+ Each backend uses its own cache to store preallocated numbers.
Numbers that are cached but not used in the current session will be
lost, resulting in "holes" in the sequence.
</para>
diff --git a/src/backend/commands/sequence.c b/src/backend/commands/sequence.c
index ca73318dc5490aa6d64e41e880bee8f38f73cd88..bb9659f359c64ede1cb661b1a6609a333bbeec85 100644
--- a/src/backend/commands/sequence.c
+++ b/src/backend/commands/sequence.c
@@ -257,7 +257,7 @@ nextval(PG_FUNCTION_ARGS)
if (rescnt > 0)
break; /* stop fetching */
if (seq->is_cycled != 't')
- elog(ERROR, "%s.nextval: got MAXVALUE (%d)",
+ elog(ERROR, "%s.nextval: reached MAXVALUE (%d)",
elm->name, maxv);
next = minv;
}
@@ -273,7 +273,7 @@ nextval(PG_FUNCTION_ARGS)
if (rescnt > 0)
break; /* stop fetching */
if (seq->is_cycled != 't')
- elog(ERROR, "%s.nextval: got MINVALUE (%d)",
+ elog(ERROR, "%s.nextval: reached MINVALUE (%d)",
elm->name, minv);
next = maxv;
}
@@ -371,21 +371,13 @@ do_setval(char *seqname, int32 next, bool iscalled)
seq = read_info("setval", elm, &buf); /* lock page' buffer and
* read tuple */
- if (seq->cache_value != 1)
- {
- elog(ERROR, "%s.setval: can't set value of sequence %s, cache != 1",
- seqname, seqname);
- }
-
if ((next < seq->min_value) || (next > seq->max_value))
- {
- elog(ERROR, "%s.setval: value %d is of of bounds (%d,%d)",
+ elog(ERROR, "%s.setval: value %d is out of bounds (%d,%d)",
seqname, next, seq->min_value, seq->max_value);
- }
/* save info in local cache */
elm->last = next; /* last returned number */
- elm->cached = next; /* last cached number */
+ elm->cached = next; /* last cached number (forget cached values) */
/* save info in sequence relation */
START_CRIT_CODE;
@@ -540,7 +532,7 @@ init_sequence(char *caller, char *name)
/* Else open and check it */
seqrel = heap_openr(name, AccessShareLock);
if (seqrel->rd_rel->relkind != RELKIND_SEQUENCE)
- elog(ERROR, "%s.%s: %s is not sequence !", name, caller, name);
+ elog(ERROR, "%s.%s: %s is not a sequence", name, caller, name);
if (elm != (SeqTable) NULL)
{
@@ -704,7 +696,7 @@ get_param(DefElem *def)
if (nodeTag(def->arg) == T_Integer)
return intVal(def->arg);
- elog(ERROR, "DefineSequence: \"%s\" is to be integer", def->defname);
+ elog(ERROR, "DefineSequence: \"%s\" value must be integer", def->defname);
return -1;
}