com.faunos.skwish.sys.filters
Class SettableSegment

java.lang.Object
  com.faunos.skwish.Segment
      com.faunos.skwish.sys.filters.SettableSegment

All Implemented Interfaces:

Range

public class SettableSegment
extends Segment

Provides a way to slip a new Segment under an existing view. The main function of this class is to provide this mechanism in a thread-safe way. This thread-safety is only achieved if the underlying segment is itself thread-safe (which usually means read-only). This requirement would usually translate to a read-only underlying implementation; but only usually, which is why this class does not enforce such a read-only rule.

Implementation Note

Under the new Java memory model, we should be able to do away with synchronization altogether in this class. At least that's how I read it in the following article.

Author:

Babak Farhang

Field Summary

Fields inherited from class com.faunos.skwish.Segment

validator

Constructor Summary

SettableSegment()
Creates a new empty instance.

SettableSegment(Segment inner)
Creates a new instance with the given initial inner instance.

Method Summary

void	delete(long id, int count, boolean purge) Deletes count entries starting at the entry with the specified id.
long	getBaseId() Returns the instance's base ID.
void	getEntry(long id, ByteBuffer out, ByteBuffer workBuffer) Returns the contents of the entry with the specified id.
FileChannel	getEntryChannel(long id) Returns the contents of the entry with the given id as a FileChannel, or null, if deleted.
long	getEntryCount() Returns the number of entries in this instance.
int	getEntryPart(long id, long position, ByteBuffer out, ByteBuffer workBuffer) Returns the specified part of the entry contents with the specified id.
long	getEntrySize(long id, ByteBuffer workBuffer) Returns the size of the entry with the specified id.
long	getNextId() Returns the ID the entry will get on the next insertion.
Segment	getSegment() Returns the underlying segment.
long	insertEntry(ByteBuffer entry) Inserts the given entry and returns the entry's ID.
long	insertEntry(ReadableByteChannel entry) Inserts the entry represented by the given channel.
boolean	isReadOnly() Determines whether this instance is read-only (unmodifiable).
boolean	isSegmentSet() Determines whether the segment has been set.
long	killNext(int count) Kills the next count entry IDs.
void	setSegment(Segment segment) Sets the underlying segment.

Methods inherited from class com.faunos.skwish.Segment

contains, delete, delete, getEntry, getEntrySize, getEntryStream, hi, isDeleted, isDeleted, killNext, lo, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

SettableSegment

public SettableSegment()

Creates a new empty instance.

See Also:

the default underlying segment, isSegmentSet()

SettableSegment

public SettableSegment(Segment inner)

Creates a new instance with the given initial inner instance.

Parameters:

inner - may not be null

Method Detail

isSegmentSet

public final boolean isSegmentSet()

Determines whether the segment has been set. When an instance is first created with the default constructor, this property is false. Once the instance is initialized with a call to setSegment(Segment) this method forever returns true.

getSegment

public final Segment getSegment()

Returns the underlying segment. All the Segment methods overridden by this class delegate to the underlying instance through this method.

setSegment

public void setSegment(Segment segment)

Sets the underlying segment. The implementation is [designed to be] thread-safe.

Note

Concurrent invocations of Segment methods overridden by this class that have yet to return may still see the previous underlying segment after this method has returned.

Parameters:

segment -

delete

public void delete(long id,
                   int count,
                   boolean purge)
            throws IOException

Description copied from class: Segment

Deletes count entries starting at the entry with the specified id. The contents of the deleted entries may optionally be requested to be purged (overwritten) immediately; o.w. the deleted contents will be purged whenever the segment is compacted or merged with another segment.

Note that purging is not part of any transaction semantic; whether or not a purge immediately takes place on its being signaled is implementation-dependent.

Specified by:

delete in class Segment

Parameters:

id - the ID of the first entry to be deleted. Must be a valid ID in this segment [baseId, baseId + entryCount)

count - the number of entries to be deleted. Specifies a range of IDs to be deleted: [id, id + count). The range of IDs must be valid entries within this segment; o.w. an exception is raised.

purge - if true, the contents of the deleted entries are signaled to be purged (overwritten) immediately; o.w. the contents will be deleted on the next time the segment is compacted.

Throws:

IOException

getBaseId

public long getBaseId()

Description copied from class: Segment

Returns the instance's base ID. An instances valid entry IDs are in the range [baseId, baseId + entryCount).

Specified by:

getBaseId in class Segment

See Also:

Segment.getEntryCount()

getEntry

public void getEntry(long id,
                     ByteBuffer out,
                     ByteBuffer workBuffer)
              throws IOException

Description copied from class: Segment

Returns the contents of the entry with the specified id. If the entry is deleted, the method returns without modifying the out buffer.

Specified by:

getEntry in class Segment

out - the buffer into which the contents are written. Its remaining bytes must be large enough; o.w., an exception is raised.

workBuffer - a work buffer used internally to read offsets. The minimum capacity of this work buffer must be 16

Throws:

IOException

getEntryChannel

public FileChannel getEntryChannel(long id)
                            throws IOException

Description copied from class: Segment

Returns the contents of the entry with the given id as a FileChannel, or null, if deleted. The returned channel is positioned at zero and is read-only.

Specified by:

getEntryChannel in class Segment

Throws:

IOException

getEntryCount

public long getEntryCount()

Description copied from class: Segment

Returns the number of entries in this instance.

Specified by:

getEntryCount in class Segment

getEntrySize

public long getEntrySize(long id,
                         ByteBuffer workBuffer)
                  throws IOException

Description copied from class: Segment

Returns the size of the entry with the specified id. A work buffer with a minimum size of 16 must be passed in.

Specified by:

getEntrySize in class Segment

Returns:

the size of the entry if present; -1, if deleted.

Throws:

IOException

getNextId

public long getNextId()

Description copied from class: Segment

Returns the ID the entry will get on the next insertion.

Specified by:

getNextId in class Segment

See Also:

ID invariants

insertEntry

public long insertEntry(ByteBuffer entry)
                 throws IOException

Description copied from class: Segment

Inserts the given entry and returns the entry's ID. The contents of the entry is understood to be the remaining contents in the given buffer.

Specified by:

insertEntry in class Segment

Parameters:

entry - they contents of the entry

Returns:

the ID assigned to the entry

Throws:

IOException

insertEntry

public long insertEntry(ReadableByteChannel entry)
                 throws IOException

Description copied from class: Segment

Inserts the entry represented by the given channel. The contents are of the entry is understood to be the entire remaining contents in the specified channel.

This is the most efficient method for inserting a large-size entry (even one that doesn't fit in memory).

Specified by:

insertEntry in class Segment

Throws:

IOException

killNext

public long killNext(int count)
              throws IOException

Description copied from class: Segment

Kills the next count entry IDs. A killed entry is an entry that begins (and ends) life in the deleted state.

Specified by:

killNext in class Segment

Parameters:

count - the number of entries to kill (must be greater than 1)

Returns:

the value that getNextId() returns after this method has completed

Throws:

IOException

isReadOnly

public boolean isReadOnly()

Description copied from class: Segment

Determines whether this instance is read-only (unmodifiable).

Specified by:

isReadOnly in class Segment

See Also:

Write operations

getEntryPart

public int getEntryPart(long id,
                        long position,
                        ByteBuffer out,
                        ByteBuffer workBuffer)
                 throws IOException

Description copied from class: Segment

Returns the specified part of the entry contents with the specified id. Up to out.remaining() bytes of the contents of the entry are copied into the given out buffer.

Specified by:

getEntryPart in class Segment

position - the starting position into the entry from where data will be copied into the out buffer

out - the out buffer into which data is written

workBuffer - a work buffer with a minimum size of 16

Returns:

the number of bytes read (possibly zero if out has no remaining bytes), or -1, if the position is greater than the size of the entry, or if the entry is deleted.

Throws:

IOException