include/emCore/emModel.h

//------------------------------------------------------------------------------
// emModel.h
//
// Copyright (C) 2005-2008,2010,2016 Oliver Hamann.
//
// Homepage: http://eaglemode.sourceforge.net/
//
// This program is free software: you can redistribute it and/or modify it under
// the terms of the GNU General Public License version 3 as published by the
// Free Software Foundation.
//
// This program is distributed in the hope that it will be useful, but WITHOUT
// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
// FOR A PARTICULAR PURPOSE. See the GNU General Public License version 3 for
// more details.
//
// You should have received a copy of the GNU General Public License version 3
// along with this program. If not, see <http://www.gnu.org/licenses/>.
//------------------------------------------------------------------------------

#ifndef emModel_h
#define emModel_h

#ifndef emRef_h
#include <emCore/emRef.h>
#endif

#ifndef emContext_h
#include <emCore/emContext.h>
#endif


//==============================================================================
//================================== emModel ===================================
//==============================================================================

class emModel : public emEngine {

public:

	// emModel is a base class for shared data and logics.
	//
	// Model references
	// ----------------
	// Models must be referred through instances of the template class
	// emRef. A model deletes itself automatically as soon as there are no
	// remaining references. It is even possible to have weak references
	// by making use of emCrossPtr.
	//
	// Model context
	// -------------
	// Each model exists within a context (see emContext, emRootContext and
	// emView). Contexts are used for grouping and refinding models. They
	// are making up a tree. Models in a root context are something like
	// "global variables".
	//
	// Common models
	// -------------
	// Models can be registered within their context so that they can be
	// refound. Registered models are called common models. The identity of
	// a common model must be unique and consists of:
	//   - The final class of the model (determined through the RTTI
	//     function typeid).
	//   - The context of the model.
	//   - The name of the model.
	// The name is a character string whose meaning is defined by derived
	// model classes. It may even be generated from model specific
	// arguments.
	//
	// Hint: a typedef does not change the result of typeid() and therefore
	// it has no effect on the identity of a model. This should not be
	// forgotten when doing something like:
	//   typedef emVarModel<int> MyIntModel;
	// Best is not to typedef models. Make derivatives instead.
	//
	// Private models
	// --------------
	// Models which are not registered for refinding, are called private
	// models. They do not need to have a unique identification and they are
	// referring a context just for convenience.
	//
	// Lifetime of common models
	// -------------------------
	// Common models can live longer than their user references. The method
	// SetMinCommonLifetime allows to set a minimum time for which the
	// context should hold the model after all other references have gone.
	// Thereby, models can easily be designed for being caches, resources,
	// configurations and so on.
	//
	// Get or create a model: the Acquire function
	// -------------------------------------------
	// Each derived model class which is not just a base class must have a
	// static method named Acquire. That function returns a reference to an
	// existing or newly created model. Constructors and destructors of
	// models are never to be called by users and should always be
	// protected.

	static emRef<emModel> Acquire(
		emContext & context, const emString & name, bool common=true
	);
		// This is an example for the Acquire function (it does not make
		// sense here because this is just a base class). The behavior
		// should always be: If common==true, search for an already
		// registered model of the same class, context and name, and if
		// it is found, return a reference to that model. Otherwise
		// create a new model, register it if common==true, and return a
		// reference to it.
		// Arguments:
		//   context - The context of the model
		//   name    - The name of the model.
		//   common  - true for refinding or creating a common model,
		//             false for creating a private model.
		// Returns: A reference to the found or created model.

	// The following two macros can be used to implement Acquire functions.
	// The first macro is for the general case, and the second is for
	// classes of models which are always common.
#	define EM_IMPL_ACQUIRE(CLASS, CONTEXT, NAME, COMMON) \
		CLASS * m; \
		if (!COMMON) m=new CLASS(CONTEXT,NAME); \
		else { \
			m=(CLASS*)CONTEXT.Lookup(typeid(CLASS),NAME); \
			if (!m) { m=new CLASS(CONTEXT,NAME); m->Register(); } \
		} \
		return emRef<CLASS >(m);
#	define EM_IMPL_ACQUIRE_COMMON(CLASS, CONTEXT, NAME) \
		CLASS * m; \
		m=(CLASS*)CONTEXT.Lookup(typeid(CLASS),NAME); \
		if (!m) { m=new CLASS(CONTEXT,NAME); m->Register(); } \
		return emRef<CLASS >(m);

	emRootContext & GetRootContext() const;
		// Get the root context.

	emContext & GetContext() const;
		// Get the context of this model.

	const emString & GetName() const;
		// Get the name of this model.

	bool IsCommon() const;
		// Ask whether this is a common model.

	bool IsRegistered() const;
		// Just a synonym for IsCommon().

	unsigned GetMinCommonLifetime() const;
	void SetMinCommonLifetime(unsigned seconds);
		// Minimum lifetime after the common model is no longer in use.
		// Zero means this model is deleted immediately when there are
		// no other references than the context. Everything greater
		// UINT_MAX/2 (or (int)seconds<0) means infinite (lifetime of
		// context). The default is zero. For private models, this
		// parameter has no meaning. Normally, SetMinCommonLifetime
		// should be called only by model constructors, not by model
		// users. Or lets say user should not shorten the lifetime.

	void Alloc();
	void Free();
		// Increment or decrement the reference counter. Free() deletes
		// this model if the reference counter gets zero. These methods
		// are usually only to be called by emRef and emContext.

	void LinkCrossPtr(emCrossPtrPrivate & crossPtr);
		// This means emCrossPtr<emModel> is possible.

protected:

	emModel(emContext & context, const emString & name);
		// Constructor.
		// Arguments:
		//   context - The context for this model
		//   name    - The name for this model.

	virtual ~emModel();
		// Destructor.

	void Register();
	void Unregister();
		// Register or unregister this model in its context.
		// IMPORTANT:
		//  - These methods must never be called from constructors or
		//    destructors of the model (directly or indirectly), because
		//    the final class is part of the registration identity, and
		//    typeid(this) does not return the final class while
		//    constructing or destructing a base class.
		//  - There must not be more than one registered model of the
		//    same class, context and name.
		//  - Usually, Register() should only be called by the Acquire
		//    functions, and Unregister() should never be called by any
		//    derivatives.

	virtual bool Cycle();
		// emModel has been derived from emEngine for convenience. This
		// default implementation does nothing and returns false.

private: friend class emContext;

	emContext & Context;
		// The context of this model.

	emString Name;
		// The name of this model.

	emCrossPtrList CrossPtrList;
		// List of cross pointers to this model.

	emAvlNode AvlNode;
		// Node for this model in the AVL tree of common models of the
		// context.

	int AvlHashCode;
		// Hash index for this model in the AVL tree of the context.
		// Or zero if this is not a common model.

	int RefCount;
		// Number of references to this model (including the context
		// when this is a common model).

	unsigned MinCommonLifetime;
		// If this is a common model: Number of seconds the context
		// should keep this model alive when there are no other
		// references. (int)MinCommonLifetime<0 means infinite.

	unsigned TimeOfDeath;
		// If this is a common model which is only referred by the
		// context: Planed time of death (in units of
		// Context.SharedTiming->SecsCounter)
};

inline emRootContext & emModel::GetRootContext() const
{
	return Context.RootContext;
}

inline emContext & emModel::GetContext() const
{
	return Context;
}

inline const emString & emModel::GetName() const
{
	return Name;
}

inline bool emModel::IsCommon() const
{
	return AvlHashCode!=0;
}

inline bool emModel::IsRegistered() const
{
	return AvlHashCode!=0;
}

inline unsigned emModel::GetMinCommonLifetime() const
{
	return MinCommonLifetime;
}

inline void emModel::Alloc()
{
	RefCount++;
}

inline void emModel::LinkCrossPtr(emCrossPtrPrivate & crossPtr)
{
	CrossPtrList.LinkCrossPtr(crossPtr);
}

inline void emModel::Register()
{
	Context.RegisterModel(this);
}

inline void emModel::Unregister()
{
	Context.UnregisterModel(this);
}


#endif