com.faunos.skwish
Class TxnSegment

java.lang.Object
  com.faunos.skwish.Segment
      com.faunos.skwish.TxnSegment

All Implemented Interfaces:

Range

public abstract class TxnSegment
extends Segment

A Segment transaction. The idea is to support multiple concurrent writers to a same logical whole segment. Each instance of this class supports a single bulk commit to the logical whole. That is, changes to the segment (both new entry insertions, and detetions of existing entries) are not saved until committed, and then only in all-or-nothing fashion.

A TxnSegment works with the union of two logical segments.

1. A snapshot of the already committed segments.
   

   This is a read-only view of the already committed segments. It is a snapshot with respect to the fact that the size of the view (the number of entries) is fixed when the transaction (a new instance of this class) is first created and does not grow even while other TxnSegments are committed. This read-only view is live in every other respect--that is, deletes committed through other transactions become immediately visible to this view.

   This "snapshot" segment contains entries with ids in the semi-open range [baseId, txnBaseId). (The txnBaseId property of the TxnSegment instance, is set at construction time to equal the nextId property of the [union of the] already committed segments.)

2. A pending/work-in-progress segment.
   

   This segment contains newly inserted entries that have yet to be committed. Ids of newly inserted entries begin at the txnBaseId property of the instance.

On commit, the committed ids of the newly inserted entries are uniformly incremented by the number entries (possibly zero) inserted by other interleaving transactions that committed before this instance. This bumping up of ids on commit happens whenever there is more than one uncommitted transaction. After commit, the instance's txnCommitIdGap property is set to the amount each newly inserted entry's id was incremented on commit.

On how to reference pending entries

Because transactions can be interleaved (i.e. by operating on multiple TxnSegment instances at a time) , its hard to tell what the final (persisted) ID of an newly inserted entry will be on commit. This presents a problem when trying to reference yet-to-be-committed entries. It presents itself in various scenarios where the entries form yet-to-be-committed object graphs across multiple transactions.

In order to address this problem, Skwish supports the notion of an abstract entry key consisting of an (entryId, txnId)-tuple that is known before commit. Here's how it works.

The user notes both entry id entryId and the txnId on inserting new entries. This txnId (transaction id) is an immutable property. After the transaction is committed, a committed entry's id can be determined by entryId += SegmentStore.getTxnCommitIdGap(txnId).

Author:

Babak Farhang

See Also:

SegmentStore.newTransaction(), SegmentStore.getTxnCommitIdGap(long)

Field Summary

Fields inherited from class com.faunos.skwish.Segment

validator

Constructor Summary

TxnSegment()

Method Summary

abstract long	commit() Commits the transaction and returns the commit ID.
abstract void	discard() Discards this transaction.
abstract FileChannel	getEntryInsertionChannel() Returns a read-write FileChannel for the next entry.
abstract FileChannel	getEntryUpdateChannel(long id) Returns a read-write FileChannel on the entry with the specified id.
abstract long	getTxnBaseId() Returns the transaction base ID, if not discarded; -1, o.w.
abstract long	getTxnCommitId() Returns the transaction commit ID, if committed; -1, o.w.
long	getTxnCommitIdGap() Returns the difference between the commit ID and the transaction base ID, if the instance is already committed; -1, o.w.
abstract long	getTxnId() Returns the transaction ID for this instance.
boolean	isAlive() Determines whether the instance is alive.
boolean	isCommitted() Determines whether the instance is committed.
boolean	isDiscarded() Determines whether the instance is discarded.

Methods inherited from class com.faunos.skwish.Segment

contains, delete, delete, delete, getBaseId, getEntry, getEntry, getEntryChannel, getEntryCount, getEntryPart, getEntrySize, getEntrySize, getEntryStream, getNextId, hi, insertEntry, insertEntry, isDeleted, isDeleted, isReadOnly, killNext, killNext, lo, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TxnSegment

public TxnSegment()

Method Detail

getTxnId

public abstract long getTxnId()
                       throws IOException

Returns the transaction ID for this instance. This id is generated on demand and is an immutable property of the instance. Invoking this method signals the library that the transaction commit id gap should be recorded on commit.

Invoking this method, therefore, incurs a cost (a 4 byte storage overhead, and 2 write accesses to that area, under the current implementation). So don't call it, if you don't need it!

Throws:

IOException

See Also:

SegmentStore.getTxnCommitIdGap(long)

getTxnBaseId

public abstract long getTxnBaseId()

Returns the transaction base ID, if not discarded; -1, o.w. Before any entries have been inserted by this instance, the segment's next ID property is equal to this property.

See Also:

discard()

commit

public abstract long commit()
                     throws IOException

Commits the transaction and returns the commit ID. Changes are propagated in all-or-nothing fashion. The transaction commit ID is set to the value returned.

After an instance has been committed, no more changes can be written to the segment.

Throws:

IOException

See Also:

getTxnCommitId()

discard

public abstract void discard()
                      throws IOException

Discards this transaction. All updates are discarded, and any subsequent invocation of a Segment method, raises an exception. On return, the transaction base ID is set to -1.

Throw this instance away after invoking this method: there's little you can do with it.

Throws:

IOException

getTxnCommitId

public abstract long getTxnCommitId()

Returns the transaction commit ID, if committed; -1, o.w. Once committed, the return value is greater than or equal the the transaction base ID.

getTxnCommitIdGap

public final long getTxnCommitIdGap()

Returns the difference between the commit ID and the transaction base ID, if the instance is already committed; -1, o.w.

isAlive

public final boolean isAlive()

Determines whether the instance is alive. An instance is alive if it is neither committed nor discarded.

isCommitted

public final boolean isCommitted()

Determines whether the instance is committed.

See Also:

getTxnCommitId()

isDiscarded

public final boolean isDiscarded()

Determines whether the instance is discarded.

See Also:

getTxnBaseId()

getEntryUpdateChannel

public abstract FileChannel getEntryUpdateChannel(long id)
                                           throws IOException

Returns a read-write FileChannel on the entry with the specified id. Note that the size of the entry may not be changed. Also, the id must belong to a newly created uncommitted entry within this transaction. (We don't yet support updating already committed entries.)

Reminder: Be sure to close the returned channel when you are done.

Returns:

a read-write FileChannel on the contents of the entry with the specified id, if the entry exists; null, o.w.

Throws:

IOException

getEntryInsertionChannel

public abstract FileChannel getEntryInsertionChannel()
                                              throws IOException

Returns a read-write FileChannel for the next entry. The returned channel is initially empty. The next entry is actually created on invoking the close method on the returned FileChannel. If another insert operation (including this one) is invoked on this instance before the returned stream is closed, then an IllegalStateException is thrown.

In order to determine what the id of this entry will be, invoke the nextId method before invoking this method.

Warning

If you discard the returned FileChannel without first closing it, this transaction instance will not allow any new entry insertions.

Throws:

IOException