added AsyncIO

Foundation/include/Poco/AsyncIOChannel.h

@@ -0,0 +1,154 @@
+//
+// AsyncIOChannel.h
+//
+// $Id: //poco/Main/Foundation/include/Poco/AsyncIOChannel.h#1 $
+//
+// Library: Foundation
+// Package: AsyncIO
+// Module:  AsyncIOChannel
+//
+// Definition of the AsyncIOChannel class.
+//
+// Copyright (c) 2007, Applied Informatics Software Engineering GmbH.
+// and Contributors.
+//
+// Permission is hereby granted, free of charge, to any person or organization
+// obtaining a copy of the software and accompanying documentation covered by
+// this license (the "Software") to use, reproduce, display, distribute,
+// execute, and transmit the Software, and to prepare derivative works of the
+// Software, and to permit third-parties to whom the Software is furnished to
+// do so, all subject to the following:
+// 
+// The copyright notices in the Software and this entire statement, including
+// the above license grant, this restriction and the following disclaimer,
+// must be included in all copies of the Software, in whole or in part, and
+// all derivative works of the Software, unless such copies or derivative
+// works are solely in the form of machine-executable object code generated by
+// a source language processor.
+// 
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
+// SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
+// FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
+// ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+// DEALINGS IN THE SOFTWARE.
+//
+
+
+#ifndef Foundation_AsyncIOChannel_INCLUDED
+#define Foundation_AsyncIOChannel_INCLUDED
+
+
+#include "Poco/Foundation.h"
+#include "Poco/ActiveDispatcher.h"
+#include "Poco/ActiveMethod.h"
+#include "Poco/AsyncIOCommand.h"
+
+
+namespace Poco {
+
+
+class Foundation_API AsyncIOChannel: public ActiveDispatcher
+	/// AsyncIOChannel supports asynchronous I/O operations on
+	/// streams or other input/output facilities.
+	///
+	/// This implementation of asynchronous I/O is based on
+	/// blocking I/O operations that are executed in a separate thread.
+	/// Some operating systems may provide special asynchronous
+	/// I/O operations at the operating system level. However, these
+	/// are not used by the current implementation.
+	///
+	/// I/O operations (in the form of AsyncIOCommand subclass instances)
+	/// are queued for execution on an AsyncIOChannel. The AsyncIOChannel's
+	/// I/O thread executes all queued commands in FIFO order.
+	///
+	/// Since AsyncIOChannel is based on ActiveDispatcher, the I/O thread is
+	/// taken from the default thread pool. It should be ensured that the
+	/// capacity of the default thread pool is sufficient before using
+	/// asynchronous I/O. For every AsyncIOChannel instance, one thread
+	/// from the default thread pool is needed.
+	///
+	/// Subclasses of AsyncIOChannel implement asynchronous input/output
+	/// for streams and sockets.
+	///
+	/// The enqueue() active member function is used to enqueue AsyncIOCommand
+	/// instances for execution.
+	///
+	/// The cancel() member function (inherited from ActiveDispatcher) can be
+	/// used to cancel all pending requests.
+	///
+	/// Both the AsyncIOCommand class, and the AsyncIOChannel class offer events
+	/// that notify an interested party about the successful or unsuccessful
+	/// completion of a command.
+	///
+	/// There are also two ways to wait for the completion of a command and
+	/// obtain its result. The first one is by using the return value of
+	/// enqueue(), which is ActiveResult<int>. See the ActiveResult class
+	/// template for more information. The second one is by using the functions
+	/// of AsyncIOCommand, such as wait(), succeeded() and result().
+	///
+	/// AsyncIOChannel supports the operations write, read and seek directly. However,
+	/// subclasses of AsyncIOChannel can define additional operations.
+{
+public:
+	ActiveMethod<int, AsyncIOCommand::Ptr, AsyncIOChannel, ActiveStarter<ActiveDispatcher> > enqueue;
+		/// Actual signature: 
+		///     int enqueueImpl(const AsyncIOCommand::Ptr& pCommand);
+		///
+		/// Enqueue the given command for eventual execution.
+		/// Returns the number of bytes read or written if the operation
+		/// was successful.
+
+	BasicEvent<AsyncIOEvent> commandCompleted;
+		/// Fired when a command has successfully completed.
+		
+	BasicEvent<AsyncIOEvent> commandFailed;
+		/// Fired when a command has failed.
+
+	virtual int write(const void* buffer, int length);
+		/// Write length bytes from buffer. 
+		///
+		/// Must be overridden by subclasses. The default implementation 
+		/// throws a NotImplementedException.
+		///
+		/// Returns the number of bytes written.
+		
+	virtual int read(void* buffer, int length);
+		/// Read up to length bytes into buffer. 
+		///
+		/// Must be overridden by subclasses. The default implementation 
+		/// throws a NotImplementedException.
+		///
+		/// Returns the number of bytes read.
+		
+	virtual int seek(std::streamoff off, std::ios::seekdir dir);
+		/// Sets the current read/write position.
+		/// 
+		/// Must be overridden by subclasses. The default implementation 
+		/// throws a NotImplementedException.
+		///
+		/// Always returns 0.
+		
+protected:
+	AsyncIOChannel();
+		/// Creates the AsyncIOChannel.
+		
+	~AsyncIOChannel();
+		/// Destroys the AsyncIOChannel.
+	
+	int enqueueImpl(const AsyncIOCommand::Ptr& pCommand);
+		/// Execute the given command by calling
+		///     pCommand->execute(this);
+		/// and return the result.
+	
+private:
+	AsyncIOChannel(const AsyncIOChannel&);
+	AsyncIOChannel& operator = (const AsyncIOChannel&);
+};
+
+
+} // namespace Poco
+
+
+#endif // Foundation_AsyncIOChannel_INCLUDED

Foundation/include/Poco/AsyncIOCommand.h

@@ -0,0 +1,319 @@
+//
+// AsyncIOCommand.h
+//
+// $Id: //poco/Main/Foundation/include/Poco/AsyncIOCommand.h#1 $
+//
+// Library: Foundation
+// Package: AsyncIO
+// Module:  AsyncIOCommand
+//
+// Definition of the AsyncIOCommand class and subclasses.
+//
+// Copyright (c) 2007, Applied Informatics Software Engineering GmbH.
+// and Contributors.
+//
+// Permission is hereby granted, free of charge, to any person or organization
+// obtaining a copy of the software and accompanying documentation covered by
+// this license (the "Software") to use, reproduce, display, distribute,
+// execute, and transmit the Software, and to prepare derivative works of the
+// Software, and to permit third-parties to whom the Software is furnished to
+// do so, all subject to the following:
+// 
+// The copyright notices in the Software and this entire statement, including
+// the above license grant, this restriction and the following disclaimer,
+// must be included in all copies of the Software, in whole or in part, and
+// all derivative works of the Software, unless such copies or derivative
+// works are solely in the form of machine-executable object code generated by
+// a source language processor.
+// 
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
+// SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
+// FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
+// ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+// DEALINGS IN THE SOFTWARE.
+//
+
+
+#ifndef Foundation_AsyncIOCommand_INCLUDED
+#define Foundation_AsyncIOCommand_INCLUDED
+
+
+#include "Poco/Foundation.h"
+#include "Poco/RefCountedObject.h"
+#include "Poco/AutoPtr.h"
+#include "Poco/Event.h"
+#include "Poco/BasicEvent.h"
+#include "Poco/AsyncIOEvent.h"
+#include "Poco/Exception.h"
+#include <ios>
+
+
+namespace Poco {
+
+
+class AsyncIOChannel;
+
+
+class Foundation_API AsyncIOCommand: public RefCountedObject
+	/// AsyncIOCommand is the base class for all asynchronous input/output
+	/// commands used with AsyncIOChannel.
+	///
+	/// See class AsyncIOChannel for more information about asynchronous input/output.
+{
+public:
+	typedef AutoPtr<AsyncIOCommand> Ptr;
+	
+	enum State
+	{
+		CMD_PENDING,     /// Command is queued for execution.
+		CMD_IN_PROGRESS, /// Command is currently being executed.
+		CMD_COMPLETED,   /// Command has completed successfully.
+		CMD_FAILED       /// Command has failed.
+	};
+	
+	BasicEvent<AsyncIOEvent> commandCompleted;
+		/// Fired when the command has successfully completed.
+		
+	BasicEvent<AsyncIOEvent> commandFailed;
+		/// Fired when the command has failed.
+	
+	State state() const;
+		/// Returns the current state of the command.
+	
+	void wait();
+		/// Waits for the completion of the command.
+	
+	void wait(long milliseconds);
+		/// Waits at most the given timeout for the 
+		/// completion of the command. Throws a
+		/// TimeoutException if the command does
+		/// not complete within the given timeout.
+		
+	bool tryWait(long milliseconds);
+		/// Waits at most the given timeout for the 
+		/// completion of the command. 
+		///
+		/// Returns true if the command completes within
+		/// the given timeout, otherwise false.
+		
+	bool succeeded() const;
+		/// Returns true iff the command completed successfully.
+		
+	bool failed() const;
+		/// Returns true iff the command has completed with an error.
+		
+	const Exception* exception() const;
+		/// If the command failed with an exception, returns a
+		/// clone of the exception. Otherwise, returns a null pointer.
+		
+	int execute(AsyncIOChannel& channel);
+		/// Executes the command on the given AsyncIOChannel.
+		///
+		/// Sets the state to CMD_IN_PROGRESS, calls
+		/// executeImpl(), and, according to its result,
+		/// sets the state to CMD_COMPLETED or CMD_FAILED
+		/// and signals the event.
+		///
+		/// Returns the number of bytes processed by the
+		/// command.
+		
+	int result() const;
+		/// Returns the result of the command.
+		
+protected:
+	AsyncIOCommand();
+		/// Creates the AsyncIOCommand.
+		
+	~AsyncIOCommand();
+		/// Destroys the AsyncIOCommand.
+	
+	virtual int executeImpl(AsyncIOChannel& channel) = 0;
+		/// Executes the command on the given AsyncIOChannel.
+		/// Must be overridded by subclasses.
+		///
+		/// Returns the number of bytes processed by the
+		/// command.
+
+private:
+	State _state;
+	Event _completed;
+	int _result;
+	Exception* _pException;
+};
+
+
+class Foundation_API AsyncWriteCommand: public AsyncIOCommand
+	/// An asynchronous write command.
+{
+public:
+	AsyncWriteCommand(const void* buffer, int length);
+		/// Create an AsyncWriteCommand for writing length bytes
+		/// from the given buffer. The given buffer must be
+		/// valid until the command completes.
+
+	const void* buffer() const;
+		/// Returns the buffer's address.
+		
+	int length() const;
+		/// Returns the buffer's size.
+
+protected:
+	int executeImpl(AsyncIOChannel& channel);
+	~AsyncWriteCommand();
+	
+private:
+	AsyncWriteCommand();
+	
+	const void* _buffer;
+	int _length;
+};
+
+
+class Foundation_API AsyncBufferedWriteCommand: public AsyncWriteCommand
+	/// An asynchronous write command. The difference to
+	/// AsyncWriteCommand is that AsyncBufferedWriteCommand 
+	/// copies the data in the buffer into an internal buffer, thus
+	/// the given buffer can be deleted as soon as the constructor
+	/// returns.
+{
+public:
+	AsyncBufferedWriteCommand(const void* buffer, int length);
+		/// Create an AsyncBufferedWriteCommand for writing length bytes
+		/// from the given buffer and copies the data from the
+		/// given buffer into an internal buffer.
+		///
+		/// The internal buffer can be accessed via the buffer()
+		/// member function inherited from AsyncWriteCommand.
+
+protected:
+	~AsyncBufferedWriteCommand();
+};
+
+
+class Foundation_API AsyncReadCommand: public AsyncIOCommand
+	/// An asynchronous read command.
+{
+public:
+	AsyncReadCommand(void* buffer, int length);
+		/// Create an AsyncReadCommand for reading up to length
+		/// bytes into the given buffer.
+
+	void* buffer() const;
+		/// Returns the buffer's address.
+		
+	int length() const;
+		/// Returns the buffer's size.
+
+protected:
+	int executeImpl(AsyncIOChannel& channel);
+	~AsyncReadCommand();
+	
+private:
+	AsyncReadCommand();
+	
+	void* _buffer;
+	int _length;
+};
+
+
+class Foundation_API AsyncBufferedReadCommand: public AsyncReadCommand
+	/// An asynchronous read command. In contrast to
+	/// AsyncReadCommand, which requires an externally supplied
+	/// buffer that must be valid until the command completes,
+	/// AsyncBufferedReadCommand maintains an internal buffer.
+{
+public:
+	AsyncBufferedReadCommand(int length);
+		/// Create an AsyncReadCommand for reading up to length
+		/// bytes into an internal buffer.
+		///
+		/// The buffer can be accessed via the buffer() member
+		/// function inherited from AsyncReadCommand.
+
+protected:
+	~AsyncBufferedReadCommand();
+};
+
+
+class Foundation_API AsyncSeekCommand: public AsyncIOCommand
+	/// An asynchronous seek command.
+{
+public:
+	AsyncSeekCommand(std::streamoff off, std::ios::seekdir dir = std::ios::beg);
+		/// Creates an AsyncSeekCommand for setting the current read/write position.
+
+protected:
+	int executeImpl(AsyncIOChannel& channel);
+	~AsyncSeekCommand();
+	
+private:
+	AsyncSeekCommand();
+	
+	std::streamoff _off;
+	std::ios::seekdir _dir;
+};
+
+
+//
+// inlines
+//
+inline AsyncIOCommand::State AsyncIOCommand::state() const
+{
+	return _state;
+}
+
+
+inline int AsyncIOCommand::result() const
+{
+	return _result;
+}
+
+
+inline const Exception* AsyncIOCommand::exception() const
+{
+	return _pException;
+}
+
+
+inline bool AsyncIOCommand::succeeded() const
+{
+	return _state == CMD_COMPLETED;
+}
+
+
+inline bool AsyncIOCommand::failed() const
+{
+	return _state == CMD_FAILED;
+}
+
+
+inline const void* AsyncWriteCommand::buffer() const
+{
+	return _buffer;
+}
+
+
+inline int AsyncWriteCommand::length() const
+{
+	return _length;
+}
+
+
+inline void* AsyncReadCommand::buffer() const
+{
+	return _buffer;
+}
+
+
+inline int AsyncReadCommand::length() const
+{
+	return _length;
+}
+
+
+} // namespace Poco
+
+
+#endif // Foundation_AsyncIOCommand_INCLUDED

Foundation/include/Poco/AsyncIOEvent.h

@@ -0,0 +1,121 @@
+//
+// AsyncIOEvent.h
+//
+// $Id: //poco/Main/Foundation/include/Poco/AsyncIOEvent.h#1 $
+//
+// Library: Foundation
+// Package: AsyncIO
+// Module:  AsyncIOEvent
+//
+// Definition of the AsyncIOEvent class.
+//
+// Copyright (c) 2007, Applied Informatics Software Engineering GmbH.
+// and Contributors.
+//
+// Permission is hereby granted, free of charge, to any person or organization
+// obtaining a copy of the software and accompanying documentation covered by
+// this license (the "Software") to use, reproduce, display, distribute,
+// execute, and transmit the Software, and to prepare derivative works of the
+// Software, and to permit third-parties to whom the Software is furnished to
+// do so, all subject to the following:
+// 
+// The copyright notices in the Software and this entire statement, including
+// the above license grant, this restriction and the following disclaimer,
+// must be included in all copies of the Software, in whole or in part, and
+// all derivative works of the Software, unless such copies or derivative
+// works are solely in the form of machine-executable object code generated by
+// a source language processor.
+// 
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
+// SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
+// FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
+// ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+// DEALINGS IN THE SOFTWARE.
+//
+
+
+#ifndef Foundation_AsyncIOEvent_INCLUDED
+#define Foundation_AsyncIOEvent_INCLUDED
+
+
+#include "Poco/Foundation.h"
+
+
+namespace Poco {
+
+
+class AsyncIOCommand;
+class AsyncIOChannel;
+
+
+class Foundation_API AsyncIOEvent
+	/// The AsyncIOEvent class holds information about an event
+	/// caused by asynchronous input or output operation.
+{
+public:
+	enum EventKind
+	{
+		EV_COMMAND_COMPLETED,
+		EV_COMMAND_FAILED
+	};
+	
+	AsyncIOEvent(AsyncIOCommand* pCommand, AsyncIOChannel* pChannel, EventKind what);
+		/// Creates the AsyncIOEvent.
+
+	AsyncIOEvent(const AsyncIOEvent& event);
+		/// Creates a AsyncIOEvent from another one.
+
+	~AsyncIOEvent();
+		/// Destroys the AsyncIOEvent.
+		
+	AsyncIOEvent& operator = (const AsyncIOEvent& event);
+		/// Assigns a AsyncIOEvent.
+		
+	void swap(AsyncIOEvent& event);
+		/// Swaps the event with another one.
+		
+	AsyncIOCommand& command() const;
+		/// Returns the command that caused the event.
+		
+	AsyncIOChannel& channel() const;
+		/// Returns the channel that caused the event.
+		
+	EventKind what() const;
+		/// Returns the reason of the event.
+
+private:
+	AsyncIOEvent();
+	
+	AsyncIOCommand* _pCommand;
+	AsyncIOChannel* _pChannel;
+	EventKind       _what;
+};
+
+
+//
+// inlines
+//
+inline AsyncIOCommand& AsyncIOEvent::command() const
+{
+	return *_pCommand;
+}
+
+
+inline AsyncIOChannel& AsyncIOEvent::channel() const
+{
+	return *_pChannel;
+}
+
+
+inline AsyncIOEvent::EventKind AsyncIOEvent::what() const
+{
+	return _what;
+}
+
+
+} // namespace Poco
+
+
+#endif // Foundation_AsyncIOEvent_INCLUDED

Foundation/include/Poco/AsyncStreamChannel.h

@@ -0,0 +1,96 @@
+//
+// AsyncStreamChannel.h
+//
+// $Id: //poco/Main/Foundation/include/Poco/AsyncStreamChannel.h#1 $
+//
+// Library: Foundation
+// Package: AsyncIO
+// Module:  AsyncStreamChannel
+//
+// Definition of the AsyncStreamChannel class.
+//
+// Copyright (c) 2007, Applied Informatics Software Engineering GmbH.
+// and Contributors.
+//
+// Permission is hereby granted, free of charge, to any person or organization
+// obtaining a copy of the software and accompanying documentation covered by
+// this license (the "Software") to use, reproduce, display, distribute,
+// execute, and transmit the Software, and to prepare derivative works of the
+// Software, and to permit third-parties to whom the Software is furnished to
+// do so, all subject to the following:
+// 
+// The copyright notices in the Software and this entire statement, including
+// the above license grant, this restriction and the following disclaimer,
+// must be included in all copies of the Software, in whole or in part, and
+// all derivative works of the Software, unless such copies or derivative
+// works are solely in the form of machine-executable object code generated by
+// a source language processor.
+// 
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
+// SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
+// FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
+// ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+// DEALINGS IN THE SOFTWARE.
+//
+
+
+#ifndef Foundation_AsyncStreamChannel_INCLUDED
+#define Foundation_AsyncStreamChannel_INCLUDED
+
+
+#include "Poco/Foundation.h"
+#include "Poco/AsyncIOChannel.h"
+#include <istream>
+#include <ostream>
+#include <iostream>
+
+
+namespace Poco {
+
+
+class Foundation_API AsyncStreamChannel: public AsyncIOChannel
+	/// AsyncStreamChannel provides an AsyncIOChannel for I/O streams.
+	///
+	/// Usage Example:
+	///     std::stringstream str;
+	///     AsyncStreamChannel channel(str);
+	///     channel.enqueue(new AsyncWriteCommand("Hello", 5));
+	///     channel.enqueue(new AsyncWriteCommand(", ", 2));
+	///     ActiveResult<int> result = channel.enqueue(new AsyncWriteCommand("world!", 6));
+	///     result.wait();
+	///     std::string s(str.str());
+{
+public:
+	AsyncStreamChannel(std::istream& istr);
+		/// Creates an AsyncStreamChannel using the given input stream.
+		/// Only read and seek operations will be allowed.
+		
+	AsyncStreamChannel(std::ostream& ostr);
+		/// Creates an AsyncStreamChannel using the given output stream.
+		/// Only write and seek operations will be allowed.
+
+	AsyncStreamChannel(std::iostream& iostr);
+		/// Creates an AsyncStreamChannel using the given input/output stream.
+
+	~AsyncStreamChannel();
+		/// Destroys the AsyncStreamChannel.
+	
+	// AsyncIOChannel
+	int write(const void* buffer, int length);
+	int read(void* buffer, int length);
+	int seek(std::streamoff off, std::ios::seekdir dir);
+			
+private:
+	AsyncStreamChannel();
+	
+	std::istream* _pIstr;
+	std::ostream* _pOstr;
+};
+
+
+} // namespace Poco
+
+
+#endif // Foundation_AsyncStreamChannel_INCLUDED