activeresult.h

This software aims to create an applet and panel tools to manage a wireless interface card, such as

//
// ActiveResult.h
//
// $Id: //poco/Main/Foundation/include/Foundation/ActiveResult.h#5 $
//
// Definition of the ActiveResult class.
//
// Copyright (c) 2004, Guenter Obiltschnig/Applied Informatics.
// All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions
// are met:
//
// 1. Redistributions of source code must retain the above copyright
//    notice, this list of conditions and the following disclaimer.
//
// 2. Redistributions in binary form must reproduce the above copyright
//    notice, this list of conditions and the following disclaimer in the
//    documentation and/or other materials provided with the distribution.
//
// 3. Redistributions in any form must be accompanied by information on
//    how to obtain complete source code for this software and any
//    accompanying software that uses this software.  The source code
//    must either be included in the distribution or be available for no
//    more than the cost of distribution plus a nominal fee, and must be
//    freely redistributable under reasonable conditions.  For an
//    executable file, complete source code means the source code for all
//    modules it contains.  It does not include source code for modules or
//    files that typically accompany the major components of the operating
//    system on which the executable file runs.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
// FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
// COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
// INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
// BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
// LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
// CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
// LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
// ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
// POSSIBILITY OF SUCH DAMAGE.
//


#ifndef Foundation_ActiveResult_INCLUDED
#define Foundation_ActiveResult_INCLUDED


#ifndef Foundation_Foundation_INCLUDED
#include "Foundation/Foundation.h"
#endif
#ifndef Foundation_Mutex_INCLUDED
#include "Foundation/Mutex.h"
#endif
#ifndef Foundation_Event_INCLUDED
#include "Foundation/Event.h"
#endif
#ifndef Foundation_RefCountedObject_INCLUDED
#include "Foundation/RefCountedObject.h"
#endif


Foundation_BEGIN


template <class ResultType>
class ActiveResultHolder: public RefCountedObject
	/// This class holds the result of an asynchronous method
	/// invocation. It is used to pass the result from the
	/// execution thread back to the invocation thread. 
	/// The class uses reference counting for memory management.
	/// Do not use this class directly, use ActiveResult instead.
{
public:
	ActiveResultHolder():
		_failed(false),
		_event(false)
		/// Creates an ActiveResultHolder.
	{
	}
	
	ResultType& data()
		/// Returns a reference to the actual result.
	{
		return _data;
	}
	
	void wait()
		/// Pauses the caller until the result becomes available.
	{
		_event.wait();
	}
	
	bool tryWait(long milliseconds)
		/// Waits up to the specified interval for the result to
		/// become available. Returns true if the result became
		/// available, false otherwise.
	{
		return _event.tryWait(milliseconds);
	}
	
	void wait(long milliseconds)
		/// Waits up to the specified interval for the result to
		/// become available. Throws a TimeoutException if the
		/// result did not became available.
	{
		_event.wait(milliseconds);
	}
	
	void notify()
		/// Notifies the invoking thread that the result became available.
	{
		_event.set();
	}
	
	bool failed() const
		/// Returns true if the active method failed (and threw an exception).
		/// Information about the exception can be obtained by calling error().
	{
		return _failed;
	}
	
	const std::string& error() const
		/// If the active method threw an exception, a textual representation
		/// of the exception is returned. An empty string is returned if the
		/// active method completed successfully.
	{
		return _error;
	}
	
	void error(const std::string& msg)
		/// Sets the failed flag and the exception message.
	{
		_error  = msg;
		_failed = true;
	}

protected:
	~ActiveResultHolder()
	{
	}

private:
	ResultType  _data;
	std::string _error;
	bool        _failed;
	Event       _event;
};


template <class RT>
class ActiveResult
	/// This class holds the result of an asynchronous method
	/// invocation (see class ActiveMethod). It is used to pass the 
	/// result from the execution thread back to the invocation thread. 
{
public:
	typedef RT ResultType;
	typedef ActiveResultHolder<ResultType> ActiveResultHolderType;

	ActiveResult(ActiveResultHolderType* pHolder):
		_pHolder(pHolder)
		/// Creates the active result. For internal use only.
	{
		poco_check_ptr (pHolder);
	}
	
	ActiveResult(const ActiveResult& result)
		/// Copy constructor.
	{
		_pHolder = result._pHolder;
		_pHolder->duplicate();
	}
	
	~ActiveResult()
		/// Destroys the result.
	{
		_pHolder->release();
	}
	
	ActiveResult& operator = (const ActiveResult& result)
		/// Assignment operator.
	{
		_pHolder->release();
		_pHolder = result._pHolder;
		_pHolder->duplicate();
	}
	
	const ResultType& data() const
		/// Returns a reference to the result data.
	{
		return _pHolder->data();
	}
	
	void wait()
		/// Pauses the caller until the result becomes available.
	{
		_pHolder->wait();
	}
	
	bool tryWait(long milliseconds)
		/// Waits up to the specified interval for the result to
		/// become available. Returns true if the result became
		/// available, false otherwise.
	{
		return _pHolder->tryWait(milliseconds);
	}
	
	void wait(long milliseconds)
		/// Waits up to the specified interval for the result to
		/// become available. Throws a TimeoutException if the
		/// result did not became available.
	{
		_pHolder->wait(milliseconds);
	}
	
	bool available() const
		/// Returns true if a result is available.
	{
		return _pHolder->tryWait(0);
	}
	
	bool failed() const
		/// Returns true if the active method failed (and threw an exception).
		/// Information about the exception can be obtained by calling error().
	{
		return _pHolder->failed();
	}
	
	const std::string& error() const
		/// If the active method threw an exception, a textual representation
		/// of the exception is returned. An empty string is returned if the
		/// active method completed successfully.
	{
		return _pHolder->error();
	}
	
	void notify()
		/// Notifies the invoking thread that the result became available.
		/// For internal use only.
	{
		_pHolder->notify();
	}
	
	ResultType& data()
		/// Returns a non-const reference to the result data. For internal
		/// use only.
	{
		return _pHolder->data();
	}
	
	void error(const std::string& msg)
		/// Sets the failed flag and the exception message.
	{
		_pHolder->error(msg);
	}
	
private:
	ActiveResult();

	ActiveResultHolderType* _pHolder;
};


Foundation_END


#endif // Foundation_ActiveResult_INCLUDED