76 lines
2.7 KiB
Plaintext
76 lines
2.7 KiB
Plaintext
m4_comment([$Id: seq_get.so,v 1.11 2005/08/09 14:23:30 bostic Exp $])
|
|
|
|
define(M4PAGELOCAL,
|
|
[seq_get])
|
|
include(m4/m4.seealso)
|
|
|
|
m4_pf_header(m4_ref(seq_get),
|
|
ifelse(M4API, C_API, [dnl
|
|
int
|
|
DB_SEQUENCE-__GT__get(DB_SEQUENCE *seq,
|
|
DB_TXN *txnid, int32_t delta, db_seq_t *retp, u_int32_t flags);
|
|
])
|
|
ifelse(M4API, CXX_API, [dnl
|
|
int
|
|
DbSequence::get(DbTxn *txnid, int32_t delta, db_seq_t *retp, u_int32_t flags);
|
|
]))
|
|
|
|
m4_p([dnl
|
|
The m4_refT(seq_get) returns the next available element in the sequence
|
|
and changes the sequence value by m4_arg(delta). The value of
|
|
m4_arg(delta) must be greater than zero. If there are enough cached
|
|
values in the sequence handle then they will be returned. Otherwise the
|
|
next value will be fetched from the database and incremented
|
|
(decremented) by enough to cover the m4_arg(delta) and the next batch
|
|
of cached values.])
|
|
|
|
m4_p([dnl
|
|
For maximum concurrency a non-zero cache size should be specified prior
|
|
to opening the sequence handle and m4_ref(DB_TXN_NOSYNC) should be
|
|
specified for each m4_refT(seq_get) call.])
|
|
|
|
m4_p([dnl
|
|
By default, sequence ranges do not wrap; to cause the sequence to wrap
|
|
around the beginning or end of its range, specify the m4_ref(DB_SEQ_WRAP)
|
|
flag to the m4_refT(seq_set_flags).])
|
|
|
|
m4_return(seq_get,
|
|
specific, EINVAL, [if the record in the database is not a valid sequence
|
|
record, or the sequence has reached the beginning or end of its range
|
|
and is not configured to wrap])
|
|
|
|
m4_parambegin
|
|
m4_param(delta, [dnl
|
|
Specifies the amount to increment or decrement the sequence.])
|
|
m4_param(flags, [dnl
|
|
m4_sf_or_may
|
|
|
|
m4_tagbegin
|
|
m4_tag(m4_idef(DB_TXN_NOSYNC), [dnl
|
|
If the operation is implicitly transaction protected (the m4_arg(txnid)
|
|
argument is NULL but the operation occurs to a transactional database),
|
|
do not synchronously flush the log when the transaction commits.])
|
|
m4_tagend])
|
|
|
|
m4_param(retp, [dnl
|
|
m4_arg(retp) points to the memory to hold the return value from
|
|
the sequence.])
|
|
m4_param_txn(seq_get,, [dnl
|
|
No m4_arg(txnid) handle may be specified if the sequence handle was
|
|
opened with a non-zero cache size.
|
|
m4_p([dnl
|
|
If the underlying database handle was opened in a transaction, calling
|
|
m4_ref(seq_get) may result in changes to the sequence object; these
|
|
changes will be automatically committed in a transaction internal to the
|
|
m4_db library. If the thread of control calling m4_ref(seq_get) has
|
|
an active transaction, which holds locks on the same database as the
|
|
one in which the sequence object is stored, it is possible for a thread
|
|
of control calling m4_ref(seq_get) to self-deadlock because the active
|
|
transaction's locks conflict with the internal transaction's locks.
|
|
For this reason, it is often preferable for sequence objects to be
|
|
stored in their own database.])])
|
|
m4_paramend
|
|
|
|
m4_seealso(DbSequence)
|
|
m4_page_footer
|