org.multiverse.api.programmatic
Interface ProgrammaticLong

public interface ProgrammaticLong

A transactional long that can be used to integrate Multiverse in environments where instrumentation is not desired or to provide access to features not yet integrated in the instrumentation (for example the commutingInc support).

It can be compared to the AtomicLong except that this ProgrammaticLong also is able to participate in full blown transactions.

A big reason why this ProgrammaticLong is added, is that it can be used as a size field in Transactional collections. Normally collections conflict on the size field even if other parts of the operations can be executed in parallel. Using the commutingInc methods it is possible to createReference commuting operations that prevent the unwanted conflict.

In Multiverse 0.6 commuting operations will be made available on a general level, but for the time being this gives the biggest bang for the buck.

Author:

Peter Veentjer

Method Summary

boolean	atomicCompareAndSet(long expected, long update) Executes a compare and set operation atomically, so it doesn't look at a running transaction stored in the ThreadLocalTransaction.
long	atomicGet() Gets the last committed value atomically without looking at a Transaction stored in the ThreadLocalTransaction.
void	atomicInc(long amount) Atomically increments the value stores in this ProgrammaticLong.
long	atomicSet(long newValue) Sets the new value and completely ignores the Transaction stored in the ThreadLocalTransaction.
void	commutingInc(long amount) Increments the value stored in this ProgrammaticReference.
void	commutingInc(Transaction tx, long amount) Increments the value stored in this ProgrammaticLong.
long	get() Gets the current value stores in this ProgrammaticLong.
long	get(Transaction tx) Gets the current value stores in this ProgrammaticLong.
void	inc(long amount) Increments the counter with the specified amount.
void	inc(Transaction tx, long amount) Increments the value stored in this ProgrammaticLong using the provided transaction.
long	set(long newValue) Sets the new value.
long	set(Transaction tx, long newValue) This call doesn't look at the ThreadLocalTransaction, so you have complete control on the transaction used.

Method Detail

get

long get()

Gets the current value stores in this ProgrammaticLong.

If an active transaction is available in the ThreadLocalTransaction, that will be used. If none is available, the get will be atomic (so be executed using its private transaction).

It is important to realize that getting a value could jeopardize the commuting behavior of this ProgrammaticLong. If you have executed commutingInc and then call this method, the operation will not commute anymore.

Returns:

the current value.

Throws:

ReadConflict

IllegalThreadStateException - if the transaction is not active.

get

long get(Transaction tx)

Gets the current value stores in this ProgrammaticLong.

This call doesn't look at the ThreadLocalTransaction, so you have complete control on the transaction used.

It is important to realize that getting a value could jeopardize the commuting behavior of this ProgrammaticLong. If you have executed commutingInc and then call this method, the operation will not commute anymore.

Parameters:

tx - the transaction to use.

Returns:

the current stored value.

Throws:

IllegalThreadStateException - if the transaction is not active.

NullPointerException - if tx is null.

ReadConflict

atomicGet

long atomicGet()

Gets the last committed value atomically without looking at a Transaction stored in the ThreadLocalTransaction.

If this call is done inside a transaction, it is possible that this call returns a value that is not correct in the eyes of the transaction. So careless use can lead to isolation problems, but correct use could allow for better scaling datastructures.

It is very likely that this call is very cheap since it doesn't need a full blown transaction.

Returns:

the last committed value.

set

long set(long newValue)

Sets the new value.

If a transaction currently is available in the ThreadLocalTransaction, it will be used. Otherwise the set will be atomic.

Parameters:

newValue - the new value to store in this ProgrammaticLong.

Returns:

the old value.

set

long set(Transaction tx,
         long newValue)

This call doesn't look at the ThreadLocalTransaction, so you have complete control on the transaction used.

Parameters:

tx - the Transaction to use.

newValue - the new value

Returns:

the old value

Throws:

IllegalThreadStateException

NullPointerException - if tx is null

ControlFlowError

atomicSet

long atomicSet(long newValue)

Sets the new value and completely ignores the Transaction stored in the ThreadLocalTransaction. If the value is not changed, it is free for the implementation to ignore this call.

It is very likely that this call is very cheap since it doesn't need a full blown transaction, but it could be that multiple retries are attempted and the transaction is backed (delayed) on failure.

Parameters:

newValue - the new value todo: exceptions

Returns:

the old value.

atomicCompareAndSet

boolean atomicCompareAndSet(long expected,
                            long update)

Executes a compare and set operation atomically, so it doesn't look at a running transaction stored in the ThreadLocalTransaction.

Provides the same behavior as the AtomicLong.compareAndSet(long, long).

Parameters:

expected - the expected value.

update - the new value

Returns:

true of the compare and swap was a success, false otherwise.

inc

void inc(long amount)

Increments the counter with the specified amount.

If a transaction currently is running in the ThreadLocalTransaction, that transaction will be used, otherwise this call will be atomic.

Parameters:

amount - the amount to increase the value with.

inc

void inc(Transaction tx,
         long amount)

Increments the value stored in this ProgrammaticLong using the provided transaction.

This call doesn't look at the ThreadLocalTransaction, so you have complete control on the transaction used.

Parameters:

tx - the Transaction to use.

amount - the amount the increase this ProgrammaticLong with.

Throws:

NullPointerException - if tx is null.

atomicInc

void atomicInc(long amount)

Atomically increments the value stores in this ProgrammaticLong. This call doesn't look at the ThreadLocalTransaction for a running transaction, but will execute inside its own (so is atomic).

It is very likely that this call is very cheap since it doesn't need a full blown transaction.

Parameters:

amount - the amount to increase the value with.

commutingInc

void commutingInc(long amount)

Increments the value stored in this ProgrammaticReference.

If a transaction is available in the ThreadLocalTransaction, that will be used. Otherwise this call will be executed atomic.

Parameters:

amount - the amount to increase with.

commutingInc

void commutingInc(Transaction tx,
                  long amount)

Increments the value stored in this ProgrammaticLong. The cool thing is that the increment is a commuting operation (so transactions that otherwise would conflict, can still both commit if the conflicting operations can commute).

Parameters:

tx - the transaction to use.

amount - the amount to increase the value with

Throws:

NullPointerException - if tx is null.

IllegalThreadStateException - if not in the correct state for this operation.