org.corfudb.runtime.object

Class VersionLockedObject<T>

java.lang.Object

org.corfudb.runtime.object.VersionLockedObject<T>

public class VersionLockedObject<T>
extends Object

The VersionLockedObject maintains a versioned object which is backed by an ISMRStream, and is optionally backed by an additional optimistic update stream.

Users of the VersionLockedObject cannot access the versioned object directly, rather they use the access() and update() methods to read and manipulate the object.

access() and update() allow the user to provide functions to execute under locks. These functions execute various "unsafe" methods provided by this object which inspect and manipulate the object state.

syncObjectUnsafe() enables the user to bring the object to a given version, and the VersionLockedObject manages any sync or rollback of updates necessary.

Created by mwei on 11/13/16.

Constructor Summary

Constructors

Constructor and Description

VersionLockedObject(Supplier<T> newObjectFn, StreamViewSMRAdapter smrStream, Map<String,ICorfuSMRUpcallTarget<T>> upcallTargets, Map<String,IUndoRecordFunction<T>> undoRecordTargets, Map<String,IUndoFunction<T>> undoTargets, Set<String> resetSet) The VersionLockedObject maintains a versioned object which is backed by an ISMRStream, and is optionally backed by an additional optimistic update stream.

Method Summary

Modifier and Type	Method and Description
<R> R	access(Function<VersionLockedObject<T>,Boolean> directAccessCheckFunction, Consumer<VersionLockedObject<T>> updateFunction, Function<T,R> accessFunction) Access the internal state of the object, trying first to optimistically access the object, then obtaining a write lock the optimistic access fails.
protected void	applyUndoRecordUnsafe(SMREntry record) Given a SMR entry with an undo record, undo the update.
void	applyUpdateToStreamUnsafe(SMREntry entry, long globalAddress) Apply an SMREntry to the version object, while doing bookkeeping for the underlying stream.
Object	applyUpdateUnsafe(SMREntry entry) Apply an SMR update to the object, possibly optimistically.
void	gc(long trimMark) Run gc on this object.
UUID	getID() Deprecated.
WriteSetSMRStream	getOptimisticStreamUnsafe() Get a handle to the optimistic stream.
long	getVersionUnsafe() Get the version of this object.
boolean	isOptimisticallyModifiedUnsafe() Check whether this object is currently under optimistic modifications.
long	logUpdate(SMREntry entry, boolean saveUpcall) Log an update to this object, noting a request to save the upcall result if necessary.
boolean	optimisticallyOwnedByThreadUnsafe() Check whether or not this object was modified by this thread.
void	optimisticCommitUnsafe() Drop the optimistic stream, effectively making optimistic updates to this object permanent.
protected void	optimisticRollbackUnsafe() Roll back the optimistic stream, resetting the object if it can not be restored.
void	resetUnsafe() Reset this object to the uninitialized state.
void	rollbackObjectUnsafe(long rollbackVersion) Roll the object back to the supplied version if possible.
protected void	rollbackStreamUnsafe(ISMRStream stream, long rollbackVersion) Roll back the given stream by applying undo records in reverse order from the current stream position until rollbackVersion.
void	seek(long globalAddress) Move the pointer for this object (effectively, forcefuly change the version of this object without playing any updates).
void	setOptimisticStreamUnsafe(WriteSetSMRStream optimisticStream) Set the optimistic stream for this thread, rolling back any previous threads if they were present.
void	syncObjectUnsafe(long timestamp) Bring the object to the requested version, rolling back or syncing the object from the log if necessary to reach the requested version.
protected void	syncStreamUnsafe(ISMRStream stream, long timestamp) Sync this stream by playing updates forward in the stream until the given timestamp.
String	toString() Generate the summary string for this version locked object.
<R> R	update(Function<VersionLockedObject<T>,R> updateFunction) Update the object under a write lock.

Methods inherited from class java.lang.Object

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

Constructor Detail

VersionLockedObject

public VersionLockedObject(Supplier<T> newObjectFn,
                           StreamViewSMRAdapter smrStream,
                           Map<String,ICorfuSMRUpcallTarget<T>> upcallTargets,
                           Map<String,IUndoRecordFunction<T>> undoRecordTargets,
                           Map<String,IUndoFunction<T>> undoTargets,
                           Set<String> resetSet)

The VersionLockedObject maintains a versioned object which is backed by an ISMRStream, and is optionally backed by an additional optimistic update stream.

Parameters:

newObjectFn - A function passed to instantiate a new instance of this object.

smrStream - Stream View backing this object.

upcallTargets - UpCall map for this object.

undoRecordTargets - Undo record function map for this object.

undoTargets - Undo functions map.

resetSet - Reset set for this object.

Method Detail

gc

public void gc(long trimMark)

Run gc on this object. Since the stream that backs this object is not thread-safe: synchronization between gc and external object access is needed.

access

public <R> R access(Function<VersionLockedObject<T>,Boolean> directAccessCheckFunction,
                    Consumer<VersionLockedObject<T>> updateFunction,
                    Function<T,R> accessFunction)

Access the internal state of the object, trying first to optimistically access the object, then obtaining a write lock the optimistic access fails.

If the directAccessCheckFunction returns true, then we execute the accessFunction without running updateFunction. If false, we execute the updateFunction to allow the user to modify the state of the object before calling accessFunction.

directAccessCheckFunction is executed under an optimistic read lock. Read-only unsafe operations are permitted.

updateFunction is executed under a write lock. Both read and write unsafe operations are permitted.

accessFunction is accessed either under a read lock or write lock depending on whether an update was necessary or not.

Type Parameters:

R - The type of the access function return.

Parameters:

directAccessCheckFunction - A function which returns True if the object can be accessed without being updated.

updateFunction - A function which is executed when direct access is not allowed and the object must be updated.

accessFunction - A function which allows the user to directly access the object while locked in the state enforced by either the directAccessCheckFunction or updateFunction.

Returns:

Returns the access function.

update

public <R> R update(Function<VersionLockedObject<T>,R> updateFunction)

Update the object under a write lock.

Type Parameters:

R - The type of the return of the updateFunction.

Parameters:

updateFunction - A function to execute once the write lock has been acquired.

Returns:

The return value of the update function.

rollbackObjectUnsafe

public void rollbackObjectUnsafe(long rollbackVersion)

Roll the object back to the supplied version if possible. This function may roll back to a point prior to the requested version. Otherwise, throws a NoRollbackException.

Unsafe, requires that the caller has acquired a write lock.

Parameters:

rollbackVersion - The version to rollback to.

Throws:

NoRollbackException - If the object cannot be rolled back to the supplied version.

seek

public void seek(long globalAddress)

Move the pointer for this object (effectively, forcefuly change the version of this object without playing any updates).

Parameters:

globalAddress - The global address to set the pointer to

syncObjectUnsafe

public void syncObjectUnsafe(long timestamp)

Bring the object to the requested version, rolling back or syncing the object from the log if necessary to reach the requested version.

Parameters:

timestamp - The timestamp to update the object to.

logUpdate

public long logUpdate(SMREntry entry,
                      boolean saveUpcall)

Log an update to this object, noting a request to save the upcall result if necessary.

Parameters:

entry - The entry to log.

saveUpcall - True, if the upcall result should be saved, false otherwise.

Returns:

The address the update was logged at.

getOptimisticStreamUnsafe

public WriteSetSMRStream getOptimisticStreamUnsafe()

Get a handle to the optimistic stream.

optimisticCommitUnsafe

public void optimisticCommitUnsafe()

Drop the optimistic stream, effectively making optimistic updates to this object permanent.

optimisticallyOwnedByThreadUnsafe

public boolean optimisticallyOwnedByThreadUnsafe()

Check whether or not this object was modified by this thread.

Returns:

True, if the object was modified by this thread. False otherwise.

setOptimisticStreamUnsafe

public void setOptimisticStreamUnsafe(WriteSetSMRStream optimisticStream)

Set the optimistic stream for this thread, rolling back any previous threads if they were present.

Parameters:

optimisticStream - The new optimistic stream to install.

getVersionUnsafe

public long getVersionUnsafe()

Get the version of this object. This corresponds to the position of the pointer into the SMR stream.

Returns:

Returns the pointer position to the object in the stream.

isOptimisticallyModifiedUnsafe

public boolean isOptimisticallyModifiedUnsafe()

Check whether this object is currently under optimistic modifications.

resetUnsafe

public void resetUnsafe()

Reset this object to the uninitialized state.

getID

@Deprecated
public UUID getID()

Deprecated.

Get the ID of the stream backing this object.

Returns:

The ID of the stream backing this object.

toString

public String toString()

Generate the summary string for this version locked object.

The format of this string is [type]@[version][+] (where + is the optimistic flag)

Overrides:

toString in class Object

Returns:

The summary string for this version locked object

applyUndoRecordUnsafe

protected void applyUndoRecordUnsafe(SMREntry record)

Given a SMR entry with an undo record, undo the update.

Parameters:

record - The record to undo.

applyUpdateUnsafe

public Object applyUpdateUnsafe(SMREntry entry)

Apply an SMR update to the object, possibly optimistically.

Parameters:

entry - The entry to apply.

rollbackStreamUnsafe

protected void rollbackStreamUnsafe(ISMRStream stream,
                                    long rollbackVersion)

Roll back the given stream by applying undo records in reverse order from the current stream position until rollbackVersion.

Parameters:

stream - The stream of SMR updates to apply in reverse order.

rollbackVersion - The version to stop roll back at.

Throws:

NoRollbackException - If an entry in the stream did not contain undo information.

syncStreamUnsafe

protected void syncStreamUnsafe(ISMRStream stream,
                                long timestamp)

Sync this stream by playing updates forward in the stream until the given timestamp. If Address.MAX is given, updates will be applied until the current tail of the stream. If Address.OPTIMISTIC is given, updates will be applied to the end of the stream, and upcall results will be stored in the resulting entries.

When the stream is trimmed, this exception is passed up to the caller, unless the timestamp was Address.MAX, in which the entire object is reset and re-try the sync, which should pick up any checkpoint that was inserted.

Parameters:

stream - The stream to sync forward

timestamp - The timestamp to sync up to.

optimisticRollbackUnsafe

protected void optimisticRollbackUnsafe()

Roll back the optimistic stream, resetting the object if it can not be restored.

applyUpdateToStreamUnsafe

public void applyUpdateToStreamUnsafe(SMREntry entry,
                                      long globalAddress)

Apply an SMREntry to the version object, while doing bookkeeping for the underlying stream.

Parameters:

entry -