Akiban Persistit 3.2.0

Milestone information

Akiban Persistit
Nathan Williams
Release registered:
No. Drivers cannot target bugs and blueprints to this milestone.  

Download RDF metadata


Assigned to you:
No blueprints or bugs assigned to you.
14 Peter Beaman
No blueprints are targeted to this milestone.
14 Fix Released

Download files for this release

File Description Downloads

Release notes 

Akiban Persistit Version 3.2.0

Release Date
October 15, 2012

Fix several critical and other bugs, one of which requires a modified
journal file format. This version also significantly improves performance
for I/O-intensive concurrent transaction loads.

See http://www.akiban.com/akiban-persistit for a summary of features and
benefits, licensing information and how to get support.

Users Guide: http://www.akiban.com/ak-docs/admin/persistit

JavaDoc: http://www.akiban.com/sites/all/libraries/persistit-api/index.html

Building Akiban-Persistit
Use Maven (maven.apache.org) to build Persistit.

To build:

 mvn install

The resulting jar files are in the target directory. To build the Javadoc:

 mvn javadoc:javadoc

The resulting Javadoc HTML files are in target/site/apidocs.

Building and Running the Examples

Small examples are located in the examples directory. Each has a short
README file describing the example, and an Ant build script
(http://ant.apache.org). After building the main akiban-persisit jar file using
Maven, you may run:

 ant run

in each of the examples subdirectories to build and run the examples.

Buffer Pool Configuration
For optimal performance, proper configuration of the Persistit buffer pool is
required. See section "Configuring the Buffer Pool" in the configuration
document http://www.akiban.com/ak-docs/admin/persistit/Configuration.html

NOTE: Especially when used with multi-gigabyte heaps, the default Hotspot
JVM server heuristics are be suboptimal for Persistit applications. Persistit
is usually configured to allocate a large fraction of the heap to Buffer
instances that are allocated at startup and held for the duration of the
Persistit instance. For efficient operation, all of the Buffer instances must
fit in the tenured (old) generation of the heap to avoid very significant
garbage collector overhead. Use either -XX:NewSize or -Xmn to adjust the
relative sizes of the new and old generations.

Resolved Issues
Persistit not recoverable after hard crash
A system experienced a sequence of events, including being killed several times
at inopportune times by the OOM Killer, that left its journal in an
unrecoverable state. Specifically, there was a journal file that contained lots
of updated pages, but no checkpoint record. Due to a bug in the RecoveryManager
code, the system timestamp was set incorrectly and led to an out-of-order page
update sequence. While this bug would be difficult to recreate by any natural
circumstances, it is critical because of potential data loss.

Accumulator state sometimes missing from checkpoint
Occasionally the state of an Accumulator was incorrect after normal system
restart. The cause was a race in the checkpoint code. This is a critical bug
due to potential data loss.

Assertion failure in TransactionIndexBucket#allocateTransactionStatus
An assert was observed in an 8-hour stress test run. The underlying cause was a
brief race condition and was harmless. The race has been fixed.

IllegalStateException due to out-of-order MVVs
Stress tests experienced an occasional occurrence of an IllegalStateException
due to out-of-order versions in an MVV value. The condition was transient and
did not cause data loss. The underlying cause has been fixed.

Join on range delete can change successor keys
A range delete that crosses at least two page boundaries can write an incorrect
key when merging records; this causes it and subsequent keys within the page to
be wrong and also leads to a discontinuity between the max key in the page and
the first key of its right sibling.

MVV and step visibility and pruning errors
Transactions using step values sometimes resulted in inconsistent states.

Page deallocation can permanently lose pages
When removing records causes deallocation of chain of pages configured in a
particular way, a garbage page, and possibly many pages linked to it, may be
stranded in a volume. The result is irrecoverable loss of space in the volume

O(N*N) Loop in JournalManager#cleanupPageList
Bad code in this method causes periodic performance degradation in 4-hour TPCC
test. The CPU cost of this algorithm scales as the square of the number of
pages in the page list, and the work is done within a globally blocking
synchronized block.

Dynamically loaded volumes not recovered "cleanly"
When a program creates new volumes using VolumeSpecifications, they
subsequently cause a "missing volume" warning from the journal copier and
prevent the removal of journal files containing the references. The journal
files accumulate seemingly without end, and each initialization of the database
seems to process more and more of the old transactions. See discussion about
regarding the useOldVSpec property.

Changes and New Features

Persistit 3.2.0 - Default Journal File Format Changed
Version 3.2.0 fixes problems related to Volumes created and opened by the
com.persistit#loadVolume method rather than being specified by the initial
system configuration. In previous versions, journal files contained
insufficient information to properly recover such volumes, even during normal

To solve this problem the format of the IV (identify volume) journal record
changed to include the com.persistit.VolumeSpecification rather than the volume
name alone. By default, journal files written by earlier versions of Persistit
continue to be supported, but once Persistit 3.2.0 has added one or more new
journal files to a database, earlier versions of Persistit are unable to open
the database.

In most cases it is never necessary to revert to an earlier version, but to
support sites where backward-compatibility may be important, it is possible to
specify a new configuration parameter (see substituteProperties(String,
Properties)). When this property is +true+, Persistit writes journal files that
are backward-compatible, but incapable of supporting dynamically created

Persistit 3.2.0 - Performance Improvements
Version 3.2.0 significantly improves I/O performance for concurrent
transactions and better controls the number of journal files created during by
very aggressive loads. A new attribute in the
com.persistit.mxbeans.JournalManagerMXBean class called
urgentFileCountThreshold controls the maximum number of journal files Persistit
will create before ramping the up the urgency of copying pages to allow purging
old files. Several other issues related to I/O scheduling and management of
dirty pages were resolved.

Version 3.2.0 significantly improves scheduling of version pruning operations.
Pruning is the process by which obsolete versions are removed from
multi-version values (MVVs). Better scheduling results in a significant
reduction in the amount of space consumed by obsolete version and also results
in better transaction throughput.

Known Issues

Transactional Tree Management
All operations within Trees such as store, fetch, remove and traverse are
correctly supported within transactions. However, the operations to create and
delete Tree instances currently do not respect transaction boundaries. For
example, if a transaction creates a new Tree, it is immediately visible within
other Transactions and will continue to exist even if the original transaction
aborts. (However, records inserted or modified by the original transaction will
not be visible until the transaction commits.) Prior to creating/removing
trees, transaction processing should be quiesced and allowed to complete.

Out of Memory Error, Direct Memory Buffer

Out of Memory Error, Direct Memory Buffer. Can cause failed transactions under
extreme load conditions as a result of threads getting backed up writing to the
journal file. However, this error is transient and recoverable by by retrying
the failed transaction.

* Workaround: Ensure your application has the ability to retry failed

Tree#getChangeCount may return inaccurate result

The getChangeCount method may return inaccurate results as its not currently
transactional. The primary consumer is the PersistitMap. As a result of this
bug Persistit may not generate java.util.ConcurrentModificationException when
it is supposed to.

Multi-Version-Values sometimes not fully pruned

Multi-version values are not always pruned properly causing volume growth. The
number of MVV records and their overhead size can be obtaining by running the
IntegrityCheck task.

* Workaround 1: Run the IntegrityCheck task (CLI command icheck) with the -P
option which will prune the MVVs. This will remove obsolete MVV instances and
in many cases free up pages in which new data can be stored. However, it will
not reduce the actual size of the volume file.

* Workaround 2: To reduce the size of the volume you can use the CLI commands
save and load to reload the data into a newly created volume file. See
http://www.akiban.com/ak-docs/admin/persistit/Management.html#management for
more information about these operations.

Note: although the methods described here may be helpful in reducing MVV
clutter, Persistit Version 3.2.0 significantly improves the algorithms used to
prune obsolete versions and the techniques described here are unlikely to be


This release does not have a changelog.

0 blueprints and 14 bugs targeted

Bug report Importance Assignee Status
1021734 #1021734 Deadlock detected in nightly stress tests 2 Critical Peter Beaman  10 Fix Released
1032392 #1032392 ArrayIndexOutOfBoundsException during TransactionTest2.transactionsWithInterrupts 2 Critical Peter Beaman  10 Fix Released
1032846 #1032846 Assertion in MVV.prune() 2 Critical Peter Beaman  10 Fix Released
1056489 #1056489 MVV and step visibility and pruning errors 2 Critical Peter Beaman  10 Fix Released
1064565 #1064565 Accumulator state sometimes missing from checkpoint 2 Critical Peter Beaman  10 Fix Released
1065677 #1065677 persisit not recoverable after hard crash 2 Critical Peter Beaman  10 Fix Released
1045971 #1045971 Dynamically loaded volumes not recovered "cleanly" 3 High Peter Beaman  10 Fix Released
1058254 #1058254 Join on range delete can change successor keys 3 High Peter Beaman  10 Fix Released
1058650 #1058650 IllegalStateException due to out-of-order MVVs 3 High Peter Beaman  10 Fix Released
1041003 #1041003 IllegalStateException in Transaction#prepare 4 Medium Peter Beaman  10 Fix Released
1053680 #1053680 Page deallocation can permanently lose pages 4 Medium Peter Beaman  10 Fix Released
1062315 #1062315 Assertion failure in TransactionIndexBucket#allocateTransactionStatus 4 Medium Peter Beaman  10 Fix Released
1029942 #1029942 Five fast years 5 Low Peter Beaman  10 Fix Released
1052508 #1052508 MissingFormatArgumentException in index page detail toString() 5 Low Peter Beaman  10 Fix Released
This milestone contains Public information
Everyone can see this information.