Akiban Persistit 3.1.2

************************************
Akiban Persistit - 3.1.2
************************************

Release Date
=============
July 13, 2012

Overview
=========
This is a bug fix release of the Persistit project

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.

Fixed Issues
=============

Infinite Loop When Repacking Buffer
-----------------------------------
https://bugs.launchpad.net/bugs/1005206

This was introduced late into the 3.1.1 development cycle. This could occur if
a buffer required restructuring during pruning of a long value that was
previously stored under a transaction. Upon the next save of this buffer to
disk (e.g. shutdown), an infinite loop would occur.

Corruption Exceptions During Various Operations
-----------------------------------------------
https://bugs.launchpad.net/bugs/1010079

NOTE:
   Only the message indicates a database corruption. The data volume is
actually correct and intact.

This was introduced late into the 3.1.1 development cycle. This could occur if
pruning a buffer containing a long record previously stored under a transaction
required removal of keys and then that buffer was reused without further
modification. A parallel structure associated with the every Buffer, the
FastIndex, was not maintained during this operation.

Slow Accumulator Operations
---------------------------
https://bugs.launchpad.net/bugs/1012859

This bug preexisted but was unknown to the 3.1.1 release. If a thread starting
a new transaction was interrupted during the call to begin(), there was a
chance for an internal object to wind up in an invalid state. This invalid
state caused no visible consequences other than slower than expected
Accumulator actions if this had occurred many times.

B+Tree Corruption in Stress Test
--------------------------------
https://bugs.launchpad.net/akiban-persistit/+bug/1017957

This bug preexisted but was unknown to the 3.1.1 release. An extremely rare
combination of events corrupted memory structures causing an incorrect
key-pointer pair to be inserted while deleting records in a key range. The bug
was detected in an 8-hour stress test run.

Slow Recovery Due to Temporary Tree IT Records
----------------------------------------------
https://bugs.launchpad.net/akiban-persistit/+bug/1018526

This bug preexisted but was unknown to the 3.1.1 release. Every Tree created in
a temporary volume was being assigned a tree handle recorded permanently in the
journal. In one case the result was a journal containing millions of IT
(Identify Tree) records, and these caused normal recovery to take a very long
time. The fix keeps temporary trees out of the journal and removes IT records
which may have been added previously.

Asserts Added to Check for Correct Exchange Thread Behavior
-----------------------------------------------------------
A bug in the Akiban Server code caused an Exchange to be used concurrently by
two Threads, causing serious and seemingly unrelated failures in Persistit
including instances of IllegalMonitorException and IllegalStateException. To
guard against future occurrences, asserts were added to catch such concurrent
use by multiple threads. Applications should be tested with asserts enabled to
verify correct thread usage.

Known Issues
=============
As described in the *3.1.1 Known Issues*.