This package defines support for structured I/O.


Interface Summary
PendingRequest.Collection The interface required for collections of pending requests.

Class Summary
BenchmarkDatagramIO Benchmarks DatagramIO.
BenchmarkDatagramIOLatency Helper class for DatagramIO latency benchmark.
BenchmarkDatagramIOReceiver Receiver-side helper class for DatagramIO throughput benchmark.
BenchmarkDatagramIOSender Sender-side helper class for DatagramIO throughput benchmark.
BenchmarkNetworkIO Benchmarks NetworkIO.
BenchmarkNetworkIOLatency Helper class for NetworkIO latency benchmark.
BenchmarkNetworkIOReceiver Receiver-side helper class for NetworkIO throughput benchmark.
BenchmarkNetworkIOSender Sender-side helper class for NetworkIO throughput benchmark.
BenchmarkTupleStore Perform tests for TupleStore operations.
DatagramIO A factory for datagram I/O clients and servers.
DatagramIO.Client An unreliable network I/O client.
DeleteRequest Implementation of a delete request.
FlushEvent Implementation of a flush event.
InputByIdResponse Implementation of an input by ID response.
InputRequest Implementation of an input request.
InputResponse Implementation of an input response.
ListenResponse Implementation of a listen response.
NetworkIO A factory for network I/O clients and servers.
NetworkIO.Server Accepts connections at a local IP address and TCP port.
OptionEvent Implementation of an option event.
OutputRequest Implementation of an output request.
OutputResponse Implementation of an output response.
PendingInputRequests Manages input requests that are waiting for matching tuples.
PendingInputRequests.Wrapper A component wrapper for the PendingInputRequests manager.
PendingRequest Encapsulates a pending input request, allowing it to be leased and removed.
Query Implementation of a query.
QueryResponse Implementation of a query response.
RemovePendingRequest Implementation of a request to remove a pending input request from a PendingInputRequests manager.
SimpleInputRequest Implementation of a simple input request.
SimpleOutputRequest Implementation of a simple output request.
SioResource Implementation of a descriptor for a structured I/O resource.
SynchronousPendingInputRequests Manages input requests that are waiting for matching tuples.
TestDatagramIO Regression tests for DatagramIO.
TestNetworkIO Regression tests for NetworkIO.
TestPendingInputRequests Regression tests for PendingInputRequests.
TestSioResource Implementation of regression tests for structured I/O resource descriptors.
TestTupleFilter Test set for TupleFilter and SerializedTupleFilter.
TestTupleStore Basic tests for TupleStore.
TupleFilter Implementation of a tuple filter, used to process queries.
TupleStore A implementation of persitant storage though structured IO.

Exception Summary
AlreadyExistsException Implementation of an already exists exception.
NoSuchTupleException Implementation of a no such tuple exception.

Package Description

This package defines support for structured I/O. Structured I/O implements input and output over tuples. The individual operations are

There are two kinds of event handlers for structured I/O. The first kind is used for structured I/O across communication channels. Handlers of the first kind only support atomic put, read, and listen operations and accept requests of type SimpleOutputRequest and SimpleInputRequest. The second kind is used for structured I/O on storage. Handlers of the second kind support all operations and, in addition to simple input and output requests, accept requests of type OutputRequest, DeleteRequest, and InputRequest. Structured I/O operations on storage are atomic by default and can optionally be executed as part of a transaction (though this feature has not yet been implemented).

The put operation on a communications channel simply puts the specified tuple into the channel. The put operation for storage adds a new tuple to the tuple store, if no tuple with the ID of the specified tuple exists in the store, and overwrites a tuple in the tuple store, if a tuple with the ID of the specified tuple already exists in the store.

The duration for read requests is the time to wait for any result before aborting the operation. The duration for query and listen requests is the requested time for the lease on the result iterator and on the listener, respectively.

Read, listen, and query operations can either return the entire matching tuple(s) or only the tuple ID(s) in their responses. Returning only the ID(s) is useful for operations that only need to confirm the arrival or existence of a tuple or subsequently delete a set of tuples.

Structured I/O event handlers signal the completion of a put operation with a OutputResponse containing the ID of the tuple written.

If reading an entire tuple, read operations return a InputResponse containing a single matching tuple if found. If there was no matching tuple, the InputResponse.tuple field is set to null. If reading only a tuple ID, read operations return a InputByIdResponse containing the ID of a single matching tuple if found. If there was no matching tuple, the InputByIdResponse.ident field is set to null.

If a delete operation actually deletes a tuple, it returns a OutputResponse containing the ID of the deleted tuple. If the store contains no tuple matching the ID of the delete request, a NoSuchTupleException is returned.

listen requests immediately return a ListenResponse containing the lease for the ongoing listen. As tuples are matched, a InputResponse is returned for each matching tuple.

query requests result in a QueryResponse containing a handler QueryResponse.iter for a query iterator as well as a handler for the lease on the iterator. To retrieve the next element found, send a IteratorRequest to the iterator handler. If a IteratorRequest is sent to an iterator for a query which returned no results, a IteratorEmpty is returned. If a IteratorRequest is sent to an iterator which has already returned all its elements, NoSuchElementException is returned.

If several read and listen operations are outstanding at the same time, a newly added tuple is first matched against any outstanding listen operations and then against any outstanding read operations. Listen operations do not consume a tuple.

Structured I/O operations may result in an exceptional event. In addition to the specific exceptions mentioned above, there are several more general exceptions returned by Structured I/O. A TransactionException signals an exceptional condition regarding a specified transaction, for example, that the transaction cannot be joined or that it is unrecognized. A LeaseException signals an exceptional condition regarding the lease for a requested listen or query operation, for example, that the requested lease has been denied. Finally, a IOException signals an exceptional condition when performing the actual I/O.

Note that IOUtilities provides several helper methods to perform structured I/O operations.

(C) Copyright 2001 UW CSE