Akiban Persistit 3.2.0

************************************
Akiban Persistit Version 3.2.0
************************************

Release Date
============
October 15, 2012

Overview
=========
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.

Documentation
==============
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
https://launchpad.net/bugs/1065677
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
https://launchpad.net/bugs/1064565
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
https://launchpad.net/bugs/1062315
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
https://launchpad.net/bugs/1058650
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
https://launchpad.net/bugs/1058254
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
https://launchpad.net/bugs/1056489
Transactions using step values sometimes resulted in inconsistent states.

Page deallocation can permanently lose pages
https://launchpad.net/bugs/1053680
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
file.

O(N*N) Loop in JournalManager#cleanupPageList
https://launchpad.net/bugs/1047973
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"
https://launchpad.net/bugs/1045971
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
startup.

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
volumes.

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
------------------------------------------------------
https://bugs.launchpad.net/akiban-persistit/+bug/985117

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
transactions

Tree#getChangeCount may return inaccurate result
-------------------------------------------------------------
https://bugs.launchpad.net/akiban-persistit/+bug/986465

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
-------------------------------------------------------------
https://bugs.launchpad.net/akiban-persistit/+bug/1000331

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
necessary.