/*
 * Copyright (c) 1999-2000, Eric Moon.
 * 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. The name of the author may not be used to endorse or promote products
 *    derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR 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.
 */


// Observe.h (cortex)
// * PURPOSE
//   Messages used for implementation of the Observer pattern.
//
// * HISTORY
//   e.moon		19aug99		Begun

#ifndef __Observe_H__
#define __Observe_H__

#include <Messenger.h>
#include <Debug.h>
#include <string.h>

#include "cortex_defs.h"
__BEGIN_CORTEX_NAMESPACE

// -------------------------------------------------------- //
// *** MESSAGES ***
// -------------------------------------------------------- //

// messages sent to the Observable (source)
enum observer_message_t {
	// Requests that an observer be added to a given
	// observable (target).
	// - "observer" (BMessenger)
	M_ADD_OBSERVER							= Observer_message_base,
	
	// Requests that a given observable (target) stop
	// sending notifications to a given observer.
	// Should be sent in response to M_RELEASE_OBSERVABLE
	// in order to allow the observable object to be deleted.
	// - "observer" (BMessenger)
	M_REMOVE_OBSERVER,
	
	// Requests that an observable quit immediately without
	// waiting for its observers to acknowledge that they're done.
	// This should only be posted to an Observable in an
	// emergency
	M_KILL_OBSERVABLE
};


// messages sent by the Observable (target)
enum target_message_t {
	// sent when the target is no longer needed; the
	// observer should reply with M_REMOVE_OBSERVER in order
	// to release (allow the deletion of) the target
	// - "target" (BMessenger)
	M_RELEASE_OBSERVABLE				= Observable_message_base,
	
	// SUGGESTED BUT NOT REQUIRED FOR IObservable IMPLEMENTATION:
	// *** IObservables are encouraged to send other replies!
	// sent upon successful receipt of M_ADD_OBSERVER
	// - "target" (BMessenger)
	M_OBSERVER_ADDED,
	
	// SUGGESTED BUT NOT REQUIRED FOR IObservable IMPLEMENTATION:
	// *** IObservables are encouraged to send other replies!
	// sent upon successful receipt of M_REMOVE_OBSERVER
	// - "target" (BMessenger)
	M_OBSERVER_REMOVED,
	
	// sent when no matching observer was found for an
	// M_REMOVE_OBSERVER message, or if the observer specified
	// in an M_ADD_OBSERVER message was previously added.
	// - "target" (BMessenger)
	// - "observer" (BMessenger)
	M_BAD_OBSERVER,
	
	// sent when the target receiving an M_ADD_OBSERVER
	// or M_REMOVE_OBSERVER didn't match the target described
	// in the message.  also sent if the target is currently
	// in the process of quitting (it's already sent M_RELEASE_OBSERVABLE
	// to its current observers, and is waiting for them to acknowledge
	// with M_REMOVE_OBSERVER so that it can delete itself.)
	// - "target" (BMessenger)
	// - "observer" (BMessenger)
	M_BAD_TARGET
};

// -------------------------------------------------------- //
// *** FUNCTIONS ***
// -------------------------------------------------------- //

// * Asynchronous

status_t add_observer(
	const BMessenger&				observer,
	const BMessenger&				target);
	
status_t remove_observer(
	const BMessenger&				observer,
	const BMessenger&				target);

// * Synchronous

status_t add_observer(
	const BMessenger&				observer,
	const BMessenger&				target,
	BMessage&								reply,
	bigtime_t								timeout =B_INFINITE_TIMEOUT);

status_t remove_observer(
	const BMessenger&				observer,
	const BMessenger&				target,
	BMessage&								reply,
	bigtime_t								timeout =B_INFINITE_TIMEOUT);
		
// -------------------------------------------------------- //
// *** TOOL CLASSES ***
// -------------------------------------------------------- //

template <class _observable_t>
class observer_handle {

public:										// ctor/dtor

	virtual ~observer_handle() {}

	observer_handle(
		const BMessenger&			observer,
		_observable_t*				target,
		bigtime_t							timeout =B_INFINITE_TIMEOUT) :
		
		_observer_messenger(observer),
		_target_messenger(target),
		_target_cache(target),
		_timeout(timeout),
		_valid(false) {
		
		BMessage reply;
		status_t err = add_observer(
			_observer_messenger,
			_target_messenger,
			reply, timeout);
		if(err < B_OK) {
			PRINT((
				"! observer_handle<>(): add_observer() failed:\n"
				"  %s\n", strerror(err)));
#if DEBUG
			PRINT((
				"  * target's reply:\n"));
			reply.PrintToStream();
#endif
		}
		else _valid = true;
	}

public:										// interface

	virtual void release() {
		if(!_valid) {
			PRINT((
				"! observer_handle<>::release(): invalid or already released.\n"));
			return;
		}
	
		BMessage reply;
		status_t err = remove_observer(
			_observer_messenger,
			_target_messenger,
			reply,
			_timeout);
		if(err < B_OK) {
			PRINT((
				"! observer_handle<>::release(): remove_observer() failed:\n"
				"  %s\n", strerror(err)));
#if DEBUG
			PRINT((
				"  * target's reply:\n"));
			reply.PrintToStream();
#endif
		}
		
		_valid = false;
	}

private:
	const BMessenger				_observer_messenger;
	BMessenger							_target_messenger;
	_observable_t*					_target_cache;
	bigtime_t								_timeout;
	bool										_valid;
};


__END_CORTEX_NAMESPACE
#endif /*__Observe_H__*/