GSIterator Class Reference

List of all members.


Detailed Description

Creates an iterator that can be used to exhaustively read through all of the visible matching entries in the space and any additional entries that match.

When creating a GSIterator one or more templates are provided (either as IEntry template or as SqlQuery). All of the entries iterated will match one or more of these templates. The templates may contain duplicates. An entry is said to be visible to an invocation of this iterator if the entry could have been returned by SpaceProxy::read using a Null Transaction (NULL_TX).

The resulting iterator initially contains all of the visible matching entries in the space (note the scope parameter). During the lifetime of the iterator an entry may be added to the iterator if it becomes visible. If the iterator's leaseDuration expires, no more entries can be added.

Iteration is done by polling results into a buffer which its size is defined by the bufferSize parameter. The buffer serves as a static snapshot of the entries in space and remains unchanged during the life of its iteration. Modifications only affect unbuffered entries. Once the buffer has been iterated over, a new buffer is polled from the space. Generally speaking, it is impossible to make any hard guarantees in the presence of concurrent modifications.

If the iteration is leased the leaseDuration must be positive. If leaseDuration is Lease::ANY (-1), the initial duration of the lease can be any positive value desired by the implementation - in this case Lease::FOREVER.

If there are remote method constraints associated with an invocation of this iterator, any remote communications performed by or on behalf of the iterator's getNext methods will be performed in compliance with these constraints, not with the constraints (if any) associated with getNext. The getNext(timeout) blocks until a next entry is available or timeout expires.

Sample usage:

Here is an example of using an iterator for iterating over matching entries:


 // Create a GSIterator using an empty Person template to match all entries
 Person personTemplate;
 GSIteratorPtr gsIterator(new GSIterator(SpaceProxy, &personTemplate, 100, ExistingAndFutureEntries, Lease::FOREVER));

 // Iterate over the entries
 PersonPtr nextPerson; 
 while (gsIterator->hasNext())
 {
	nextPerson.reset((Person*)gsIterator->getNext());
 }
 

Here is an example of using a blocking iterator for iterating over matching entries:


 // Prepare the templates (matching both Message and Payload objects)
 Message msgTemplate;
 Payload payloadTemplate;
 std::vector<IEntry*> tmplsArray;
 tmplsArray.push_back(&msgTemplate);
 tmplsArray.push_back(&payloadTemplate);
 // Create the GSIterator using the array of the 2 templates
 GSIteratorPtr gsIterator(new GSIterator(SpaceProxy, tmplsArray, 100, ExistingAndFutureEntries, Lease::FOREVER));

 // Iterate over all matching entries until iteration is exhausted
 IEntryPtr nextValue; 
 const long NEXT_TIMEOUT = 30000; //30 seconds
 while (true)
 {
	nextValue.reset(gsIterator->getNext(NEXT_TIMEOUT));
	if (nextValue == NULL)
		break;
 }
 

Note:
This implementation is not synchronized. If multiple threads access this iterator concurrently, it must be synchronized externally.
Author:
Irit Rosdeutscher
See also:
SpaceProxy

Public Member Functions

long long getExpiration ()
 Returns the absolute time that the lease will expire, represented as milliseconds from the beginning of the epoch.
IEntrygetNext (long long timeout)
 Same as getNext() but with blocking behavior, blocking until a matched entry is available or until timeout expires.
IEntrygetNext ()
 Removes one entry from the iterated buffered set and returns a copy to the caller.
 GSIterator (SpaceProxyPtr space, const SqlQuery &sqlQuery, int bufferSize=100, IteratorScope scope=FutureEntries, long long leaseDuration=Lease::FOREVER)
 Constructs an iterator over a space using a single SqlQuery template in order to incrementally return the matching entries.
 GSIterator (SpaceProxyPtr space, const std::vector< SqlQuery > &sqlArray, int bufferSize=100, IteratorScope scope=FutureEntries, long long leaseDuration=Lease::FOREVER)
 Constructs an iterator over a space using a collection of SqlQuery templates in order to incrementally return the matching entries.
 GSIterator (SpaceProxyPtr space, IEntry *pIEntryTemplate, int bufferSize=100, IteratorScope scope=FutureEntries, long long leaseDuration=Lease::FOREVER)
 Constructs an iterator over a space using a single template in order to incrementally return the matching entries.
 GSIterator (SpaceProxyPtr space, const std::vector< IEntry * > &tmplsArray, int bufferSize=100, IteratorScope scope=FutureEntries, long long leaseDuration=Lease::FOREVER)
 Constructs an iterator over a space using a collection of templates in order to incrementally return the matching entries.
bool hasNext ()
 Returns true if the iterator has more elements to iterate over.
void renew (long long duration)
 Renews iterator's lease.
virtual ~GSIterator ()
 Performs cleanup, particularly cancels the iterator.

Constructor & Destructor Documentation

GSIterator::GSIterator ( SpaceProxyPtr  space,
const std::vector< IEntry * > &  tmplsArray,
int  bufferSize = 100,
IteratorScope  scope = FutureEntries,
long long  leaseDuration = Lease::FOREVER 
)

Constructs an iterator over a space using a collection of templates in order to incrementally return the matching entries.

Some operations on a space must return more entries than can be conveniently returned by a single call, generally because returning all the entries in one result would consume too many resources in the client or introduce too much latency before the first entry could be processed. In these cases, iterators are used to incrementally return the necessary entries. A GSIterator instance is used to access a set of matches returned by getNext.

The iterator will initially contain some population of entries. These entries can be retrieved by calling getNext. A successful call to getNext will remove the returned entry from the iteration. An iterator can end up in one of two terminal states, invalidated or exhausted.

A leased iterator which expires is considered as invalidated. A cancelled iterator is an exhausted iterator and will have no more entries added to it. Calling getNext on an iterator with either state always returns NULL. There is no guarantee that once getNext returns NULL, all future calls on that GSIterator instance will do the same.

Between the time an iterator is created and the time it reaches a terminal state, entries may be added by the space. However, an entry that is removed by a getNext call may be added back to the iterator if its uniqueness is equivalent. The space may also update or remove entries that haven't yet been returned by a getNext call, and are not part of the buffered set.

If there is a possibility that an iterator may become invalidated, it must be leased. If there is no possibility that the iterator will become invalidated, implementations should not lease it (i.e. use Lease::FOREVER). If there is no further interest an iterator may be cancelled. Note that it is automatically cancelled by the destructor.

An active lease on an iterator serves as a hint to the space that the client is still interested in matching entries, and as a hint to the client that the iterator is still functioning. There are cases, however, where this may not be possible. In particular, it is not expected that iteration will maintain across crashes. If the lease expires the iterator is invalidated. Clients should not assume that the resources associated with a leased match set will be freed if the match set reaches the exhausted state, and should instead cancel the lease, or remove the GSIterator instance.

Parameters:
space - Space proxy to iterate on
tmplsArray - Vector of entry templates. All the entries added to the resulting match set will match one or more elements of tmplsArray.
bufferSize - The maximum number of entries to pool each time from the space. Default is 100.
scope - Use ExistingAndFutureEntries to initially contain all of the visible matching entries in the space. Use FutureEntries (default) to contain only visible matching entries thereafter.
leaseDuration - The requested initial lease time (in milliseconds) on the resulting match set. Default is Lease::FOREVER.
Exceptions:
RemoteException - if a communication error occurs
UnusableEntryException - if history contains an unusable entry
IllegalArgumentException - if tmplsArray is empty or NULL, or if bufferSize is non-positive, or if leaseDuration is neither positive nor Lease::ANY (-1).

GSIterator::GSIterator ( SpaceProxyPtr  space,
IEntry pIEntryTemplate,
int  bufferSize = 100,
IteratorScope  scope = FutureEntries,
long long  leaseDuration = Lease::FOREVER 
)

Constructs an iterator over a space using a single template in order to incrementally return the matching entries.

Same as GSIterator(SpaceProxyPtr, const std::vector<IEntry*>&, int, IteratorScope, long long) except that only a single entry template is given.

Parameters:
space - Space proxy to iterate on
pIEntryTemplate - Entry template
bufferSize - The maximum number of entries to pool each time from the space. Default is 100.
scope - Use ExistingAndFutureEntries to initially contain all of the visible matching entries in the space. Use FutureEntries (default) to contain only visible matching entries thereafter.
leaseDuration - The requested initial lease time (in milliseconds) on the resulting match set. Default is Lease::FOREVER.

GSIterator::GSIterator ( SpaceProxyPtr  space,
const std::vector< SqlQuery > &  sqlArray,
int  bufferSize = 100,
IteratorScope  scope = FutureEntries,
long long  leaseDuration = Lease::FOREVER 
)

Constructs an iterator over a space using a collection of SqlQuery templates in order to incrementally return the matching entries.

Same as GSIterator(SpaceProxyPtr, const std::vector<IEntry*>&, int, IteratorScope, long long) except that the entry templates are provided as SqlQuery.

Parameters:
space - Space proxy to iterate on
sqlArray - Vector of SqlQuery elements that represent entry templates. All the entries added to the resulting match set will match one or more elements of sqlArray.
bufferSize - The maximum number of entries to pool each time from the space. Default is 100.
scope - Use ExistingAndFutureEntries to initially contain all of the visible matching entries in the space. Use FutureEntries (default) to contain only visible matching entries thereafter.
leaseDuration - The requested initial lease time (in milliseconds) on the resulting match set. Default is Lease::FOREVER.

GSIterator::GSIterator ( SpaceProxyPtr  space,
const SqlQuery sqlQuery,
int  bufferSize = 100,
IteratorScope  scope = FutureEntries,
long long  leaseDuration = Lease::FOREVER 
)

Constructs an iterator over a space using a single SqlQuery template in order to incrementally return the matching entries.

Same as GSIterator(SpaceProxyPtr, const std::vector<SqlQuery>&, int, IteratorScope, long long) except that only a single SqlQuery template is given.

Parameters:
space - Space proxy to iterate on
sqlQuery - SqlQuery template
bufferSize - The maximum number of entries to pool each time from the space. Default is 100.
scope - Use ExistingAndFutureEntries to initially contain all of the visible matching entries in the space. Use FutureEntries (default) to contain only visible matching entries thereafter.
leaseDuration - The requested initial lease time (in milliseconds) on the resulting match set. Default is Lease::FOREVER.

GSIterator::~GSIterator ( void   )  [virtual]

Performs cleanup, particularly cancels the iterator.


Member Function Documentation

long long GSIterator::getExpiration (  ) 

Returns the absolute time that the lease will expire, represented as milliseconds from the beginning of the epoch.

Note that the expiration time is calculated based on local clock.

Returns:
A long value in milliseconds from the beginning of the epoch that represents the absolute time that the lease will expire.

IEntry * GSIterator::getNext ( long long  timeout  ) 

Same as getNext() but with blocking behavior, blocking until a matched entry is available or until timeout expires.

Parameters:
timeout - Time to wait until a next element is available (in milliseconds).
Returns:
Pointer to an entry from the iterated buffered set, or NULL if no match found in the given timeout.

IEntry * GSIterator::getNext (  ) 

Removes one entry from the iterated buffered set and returns a copy to the caller.

Returns NULL if a call to hasNext would have returned false.

A given invocation of this method may perform remote communications, retrieving the next buffer set, but generally the getNext method is not expected to have remote method constraints that can vary from invocation to invocation.

Returns:
Pointer to an entry from the iterated buffered set, or NULL if the iterated set is empty or presumably complete.

bool GSIterator::hasNext (  ) 

Returns true if the iterator has more elements to iterate over.

If the iterator was constructed to initially contain matching entries, then hasNext() will return true until the entire initial set has been iterated over. Still, hasNext() may return false iterating over any additional matching entries due to communication constraints - thus, it does not guarantee that the iterator is in one of its terminal states. It is advised to use ACE_OS::sleep between subsequent calls, to allow the iterator to receive possible additional matches.

Returns:
true if the iterator has more matches; false if currently there are no more available matches to return from a call to getNext().

void GSIterator::renew ( long long  duration  ) 

Renews iterator's lease.

Use this to renew the iterator's lease for an additional period of time, specified in milliseconds. This duration is not added to the original lease, but is used to determine a new expiration time for the existing lease. If the renewal is granted this is reflected in the value returned by getExpiration. If the renewal fails, the lease is left intact for the same duration that was in force prior to the call to renew.

An expired iterator is an invalidated iterator and will have no more entries added to it. Subsequent calls to getNext on this iterator will always return NULL.

Parameters:
duration - The requested duration in milliseconds
Exceptions:
IllegalArgumentException - if lease expiration time is invalid
LeaseDeniedException - if the iterator's lease has already expired


Generated on Thu Jul 22 08:11:54 2010 for GigaSpaces XAP 10.2.1 C++ by  doxygen 1.5.3