lights
Class TupleSpace

java.lang.Object
  |
  +--lights.TupleSpace

All Implemented Interfaces:

ITupleSpace, java.io.Serializable

public class TupleSpace

extends java.lang.Object

implements ITupleSpace, java.io.Serializable

Embodies the concept of a Linda-like tuple space. The traditional operations provided by Linda, namely the insertion of a tuple with out and pattern matching with the blocking operations in and rd, are supported. In addition, the following features are provided:

• non-blocking probe operations inp and rdp;
• group operations outg, ing, rdg, that allow to write and retrieve multiple tuples at once;
• a count operation returning the number of tuples matching a given template;
• a name associated to the tuple space.

The semantics of the tuple space are such that a copy of the original tuple is inserted. In other words, modifications to the tuple object subsequent to insertion are not reflected into the tuple object stored into the tuple space. This semantics is ensured by serializing and deserializing the tuple object being inserted, in order to obtain a deep copy of the tuple that is the one actually inserted in the tuple space.

Tuple space access can be optimized for space or speed, by specifying the desired policy (SPACE or SPEED) at creation time. In the former case, each time a tuple is retrieved it is serialized and deserialized to ensure the copy semantics. In the latter case, a copy of the serialized form is stored with the tuple at insertion time. This way, a copy can be retrieved by performing the deserialization only. This is the default policy.

Version:

1.0

Author:

Gian Pietro Picco

See Also:

Serialized Form

Field Summary

protected int	optimizationFor The default for optimization is speed.
static int	SPACE Used to specify that tuple space access should be optimized for space.
static int	SPEED Used to specify that tuple space access should be optimized for speed.
protected java.util.Vector	ts The actual implementation of the tuple space data structure.

Fields inherited from interface lights.interfaces.ITupleSpace

DEFAULT_NAME

Constructor Summary

TupleSpace()
Creates a tuple space with a default name, and optimization for speed.

TupleSpace(java.lang.String name)
Creates a tuple space with the name specified by the user, and optimization for speed.

TupleSpace(java.lang.String name, int optimizeFor)
Creates a tuple space with the name and optimization specified by the user.

Method Summary

int	count(ITuple template) Returns a count of the tuples found in the tuple space that match the template.
java.lang.String	getName() Returns the name of the tuple space.
ITuple	in(ITuple template) Withdraws from the tuple space a tuple matching the template specified; if no tuple is found, the caller is suspended until such a tuple shows up in the tuple space.
ITuple[]	ing(ITuple template) Withdraws from the tuple space all the tuple matching the template specified.
ITuple	inp(ITuple template) Withdraws from the tuple space a tuple matching the template specified; if no tuple is found, null is returned.
void	out(ITuple tuple) Inserts a tuple in the tuple space.
void	outg(ITuple[] tuples) Inserts multiple tuples in the tuple space.
ITuple	rd(ITuple template) Reads from the tuple space a copy of a tuple matching the template specified.
ITuple[]	rdg(ITuple template) Reads from the tuple space a copy of all the tuples matching the template specified.
ITuple	rdp(ITuple template) Reads from the tuple space a copy of a tuple matching the template specified.
java.lang.String	toString() Returns a string representation of the tuple space.

Methods inherited from class java.lang.Object

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

Field Detail

SPEED

public static final int SPEED

Used to specify that tuple space access should be optimized for speed.

SPACE

public static final int SPACE

Used to specify that tuple space access should be optimized for space.

ts

protected java.util.Vector ts

The actual implementation of the tuple space data structure.

optimizationFor

protected int optimizationFor

The default for optimization is speed.

Constructor Detail

TupleSpace

public TupleSpace()

Creates a tuple space with a default name, and optimization for speed.

TupleSpace

public TupleSpace(java.lang.String name)

Creates a tuple space with the name specified by the user, and optimization for speed.

Parameters:

name - the tuple space name.

Throws:

java.lang.IllegalArgumentException - if the name is null.

TupleSpace

public TupleSpace(java.lang.String name,
                  int optimizeFor)

Creates a tuple space with the name and optimization specified by the user.

Parameters:

name - the tuple space name.

optimizeFor - either of the values SPACE and SPEED.

Throws:

java.lang.IllegalArgumentException - if the optimization parameter is not valid, or the name is null.

Method Detail

getName

public java.lang.String getName()

Returns the name of the tuple space.

Specified by:

getName in interface ITupleSpace

out

public void out(ITuple tuple)
         throws TupleSpaceException

Inserts a tuple in the tuple space. The operation is synchronous, i.e., the tuple is guaranteed to be available in the tuple space after this method successfully completes execution.

Specified by:

out in interface ITupleSpace

Parameters:

tuple - The tuple to be inserted.

Throws:

TupleSpaceException - if an error occurs in the implementation.

java.lang.IllegalArgumentException - if the tuple has no fields.

outg

public void outg(ITuple[] tuples)
          throws TupleSpaceException

Inserts multiple tuples in the tuple space. The operation is performed atomically, i.e., each tuple is not available until all the tuples have been inserted.

Specified by:

outg in interface ITupleSpace

Parameters:

tuples - An array containing the tuples to be inserted.

Throws:

TupleSpaceException - if an error occurs in the implementation.

in

public ITuple in(ITuple template)
          throws TupleSpaceException

Withdraws from the tuple space a tuple matching the template specified; if no tuple is found, the caller is suspended until such a tuple shows up in the tuple space. If multiple matching tuples are found, the one returned is selected non-deterministically.

Specified by:

in in interface ITupleSpace

Parameters:

template - the template used for matching.

Returns:

a tuple matching the template.

Throws:

TupleSpaceException - if an error in the implementation.

inp

public ITuple inp(ITuple template)
           throws TupleSpaceException

Withdraws from the tuple space a tuple matching the template specified; if no tuple is found, null is returned. If multiple matching tuples are found, the one returned is selected non-deterministically.

Specified by:

inp in interface ITupleSpace

Parameters:

template - the template used for matching.

Returns:

a tuple matching the template, or null if none is found.

Throws:

TupleSpaceException - if an error in the implementation.

ing

public ITuple[] ing(ITuple template)
             throws TupleSpaceException

Withdraws from the tuple space all the tuple matching the template specified. If no tuple is found, null is returned.

Specified by:

ing in interface ITupleSpace

Parameters:

template - the template used for matching.

Returns:

a tuple matching the template, or null if none is found.

Throws:

TupleSpaceException - if an error in the implementation.

rd

public ITuple rd(ITuple template)
          throws TupleSpaceException

Reads from the tuple space a copy of a tuple matching the template specified. If no tuple is found, the caller is suspended until such a tuple shows up in the tuple space. If multiple matching tuples are found, the one returned is selected non-deterministically.

Specified by:

rd in interface ITupleSpace

Parameters:

template - the template used for matching.

Returns:

a copy of a tuple matching the template.

Throws:

TupleSpaceException - if an error in the implementation.

rdp

public ITuple rdp(ITuple template)
           throws TupleSpaceException

Reads from the tuple space a copy of a tuple matching the template specified. If no tuple is found, null is returned. If multiple matching tuples are found, the one returned is selected non-deterministically.

Specified by:

rdp in interface ITupleSpace

Parameters:

template - the template used for matching.

Returns:

a copy of a tuple matching the template, or null if none is found.

Throws:

TupleSpaceException - if an error in the implementation.

rdg

public ITuple[] rdg(ITuple template)
             throws TupleSpaceException

Reads from the tuple space a copy of all the tuples matching the template specified. If no tuple is found, null is returned. Conventionally, a tuple with no fields matches any other tuple.

Specified by:

rdg in interface ITupleSpace

Parameters:

template - the template used for matching.

Returns:

a copy of a tuple matching the template, or null if none is found.

Throws:

TupleSpaceException - if an error in the implementation.

count

public int count(ITuple template)
          throws TupleSpaceException

Returns a count of the tuples found in the tuple space that match the template.

Specified by:

count in interface ITupleSpace

Parameters:

template - the template used for matching.

Returns:

the number of tuples currently in the tuple space that match the template.

Throws:

TupleSpaceException - if an error in the implementation.

toString

public java.lang.String toString()

Returns a string representation of the tuple space.

Overrides:

toString in class java.lang.Object