TerrainBasicImp.H

Go to the documentation of this file.

#ifndef TerrainBasicImp_H
#define TerrainBasicImp_H

// $Id: TerrainBasicImp.H 5279 2007-06-23 02:49:08Z mburo $
// This is an ORTS file (c) Michael Buro, David Deutscher, licensed under the GPL


#include "TerrainBase.H"
#include "GameObj.H"

/// \brief Implementation of common Task bookkeeping for TerrainBase implementations.
/** 
TerrainBasicImp is templated on a TaskWrapper type, which should include 
a "Task task" member, a TaskWrapper(const Task&) constructor, and any 
other data that the derived implementation needs.

It maintains a "tasks" container for all TaskWrapper objects, and a queue of 
TaskWrapper iterators pointing on pending (requested but not planned yet) tasks.
Also maintained are maps from TaskId to a TaskWrapper, from an Object* to the
task for moving it, and a multimap from an Object* to all tasks in which it is 
the target of movement.
Derived classes are responsible to remove a TaskWrapper from the pending list,
and for applying some logic to cases where the target object of a task is removed
(dies or vanishes).

TerrainBasicImp implements: 
add_task, remove_task, cancel_task - as expected.
remove_obj - delete relevant tasks and mappings, if any.
Derived classes that implement these methods should call these ancestor 
versions (of course, call remove/cancal after any code that depends on
the respective data..).

REGISTER_TYPEOF issue: since this is a template, no REGISTER_TYPEOF's are
done. Users of the class must explicitly use relevant REGISTER_TYPEOF, and
avoid conflicts if using the same TaskWrapper more than once.
The 'REGISTER_TYPEOFS_TerrainBasicImp' macro might be useful.
*/
template<class TaskWrapper>
class TerrainBasicImp : public TerrainBase
{
public:
  
  //---------------------------------------------------------------------
  /// \name Internal typedefs
  /// public to allow REGISTER_TYPEOF definitions
  //---------------------------------------------------------------------
  //@{
  /* Using a std::list:
     1. allows storing iterators, as these are valid even when changing the list.
     2. allows fast push_back, fast erase in the middle
  */
  typedef std::list<TaskWrapper>                            Tasks;
  typedef typename Tasks::iterator                          TIter;
  /* Using a deque allows FIFO handling of incoming tasks.
     The linear find-to-erase operation is tolerable since the queue 
     is expected to remain relatively small. */
  typedef std::deque<TIter>                                 TaskQueue;
  typedef std::map<TerrainBase::TaskId,TIter>               TaskId2Task;
  typedef std::map<const Object*,TerrainBase::TaskId>       Obj2TaskId;
  typedef std::multimap<const Object*,TerrainBase::TaskId>  ObjIsGoalInTaskId;
  //@}
  //---------------------------------------------------------------------


  TerrainBasicImp() {};
  TerrainBasicImp(const TerrainBasicImp &other) 
    : TerrainBase(other), tasks(other.tasks), pendingTasks(other.pendingTasks), 
      taskId2task(other.taskId2task), obj2taskId(other.obj2taskId),
      objIsGoalInTaskId(other.objIsGoalInTaskId) {};
  virtual ~TerrainBasicImp() {};

  
  //---------------------------------------------------------------------
  /// \name Implementations for abstract TerrainBase Task-handling methods.
  /** Some of the method implementations are empty stubs, allowing derived
      classes to call TerrainBasicImp::X() as the first action in each method.
      Since this call is needed in remove_obj() (to remove tasks associated with
      this object), completeness calls for creating these stubs.
  */
  //---------------------------------------------------------------------
  //@{
  virtual TaskId add_task(const TerrainBase::Task &task);
  virtual void remove_task(TerrainBase::TaskId tid);
  virtual void cancel_task(const Object *obj);

  virtual void add_obj(const Object *obj);
  virtual void remove_obj(const Object *obj);
  virtual void update_obj(const Object *obj);
  virtual void add_segments(const Vector<Segment> &segs);
  //@}
  //---------------------------------------------------------------------


protected:
  //---------------------------------------------------------------------
  /// \name Internal removal of tasks
  /** These methods should be called internally (including by derived classes)
      to remove tasks, to differentiate requests by the outside world from internal
      bookkeeping. For example, add_task() first removes any existing tasks for
      the same objects, but this should not create stop-actions for them, etc.
  */
  //---------------------------------------------------------------------
  //@{
  virtual void clean_task_for_obj(const Object *obj);
  virtual void clean_task(TerrainBase::TaskId task_id);
  //@}
  //---------------------------------------------------------------------

  void eraseFromFailed(const TIter& it);
  void eraseFromPending(const TIter& it);
  void eraseObjIsGoalFor(const typename TaskId2Task::iterator& ti2tIt);

  //---------------------------------------------------------------------
  /// \name Internal book-keeping of tasks
  //---------------------------------------------------------------------
  //@{
  Tasks             tasks;
  TaskQueue         pendingTasks;
  TaskQueue         failedTasks; //not necessarily used in every pathfinder, so probably doesn't belong here, but it was the easiest for now -Nick W.
  TaskId2Task       taskId2task;
  Obj2TaskId        obj2taskId;
  ObjIsGoalInTaskId objIsGoalInTaskId;
  //@}
  //---------------------------------------------------------------------

private:
  TerrainBasicImp operator=(const TerrainBasicImp&); // don't need it
};

//---------------------------------------------------------------------
//---------------------------------------------------------------------

#define REGISTER_TYPEOFS_TerrainBasicImp_OneTime(N,template_arg) \
  REGISTER_TYPEOF(N+0, TerrainBasicImp<template_arg>::Obj2TaskId::iterator); \
  REGISTER_TYPEOF(N+1, TerrainBasicImp<template_arg>::Obj2TaskId::const_iterator);
//  REGISTER_TYPEOF(N+2, TerrainBasicImp<template_arg>::ObjIsGoalInTaskId::iterator);
//  REGISTER_TYPEOF(N+3, TerrainBasicImp<template_arg>::ObjIsGoalInTaskId::const_iterator);

#define REGISTER_TYPEOFS_TerrainBasicImp_ForEach(N,template_arg) \
  REGISTER_TYPEOF(N+0, TerrainBasicImp<template_arg>::Tasks::iterator); \
  REGISTER_TYPEOF(N+1, TerrainBasicImp<template_arg>::Tasks::const_iterator); \
  REGISTER_TYPEOF(N+2, TerrainBasicImp<template_arg>::TaskId2Task::iterator); \
  REGISTER_TYPEOF(N+3, TerrainBasicImp<template_arg>::TaskId2Task::const_iterator); \
  REGISTER_TYPEOF(N+4, TerrainBasicImp<template_arg>::TaskQueue::iterator); \
  REGISTER_TYPEOF(N+5, TerrainBasicImp<template_arg>::TaskQueue::const_iterator); \
  REGISTER_TYPEOF(N+6, Vector<TerrainBasicImp<template_arg>::TIter>::iterator); \
  REGISTER_TYPEOF(N+7, Vector<TerrainBasicImp<template_arg>::TIter>::const_iterator);

//---------------------------------------------------------------------
template<class TaskWrapper>
TerrainBase::TaskId TerrainBasicImp<TaskWrapper>::add_task(const TerrainBase::Task &task)
{
  // These loops of asserts are used to ensure that no module is sending
  // a pathfinding request with a vector containing anything other than
  // valid GameObj instances. Since this check occurs before the task is
  // queued, a failure will occur in the same stack trace that contains
  // the faulty code which originally fired the pathfind request Event.

#ifndef NDEBUG
  FORALL(task.objs, o) {
    const GameObj * obj = dynamic_cast<const GameObj*>( (*o) );
    assert( obj != NULL );
  }
#endif

  TaskWrapper tw(task);

#ifndef NDEBUG  
  // These loops of asserts simply guarantee that our TaskWrapper, when
  // initialized with a valid Task, in turn has a vector containing 
  // nothing but valid GameObj instances.
  FORALL(tw.task.objs, o) {
    const GameObj * obj = dynamic_cast<const GameObj*>( (*o) );
    assert( obj != NULL );
  }
#endif
  
  tw.isPending = true;

  //tasks.push_back(tw);
  //TIter pos = tasks.back();
  TIter pos = tasks.insert(tasks.end(),tw);
  // currently, the taskID is just the address of the allocated taskwrapper in the list.
  TerrainBase::TaskId id = (TerrainBase::TaskId)&(*pos);
  // insert to the maps
  taskId2task[id] = pos;
  FORALL(task.objs, objIt) {
    clean_task_for_obj(*objIt);
    obj2taskId[*objIt] = id;
  }
  if( task.goal.target == TerrainBase::Goal::OBJ )  {
    objIsGoalInTaskId.insert(ObjIsGoalInTaskId::value_type(task.goal.obj, id));
  }
  
  // mark the new task as pending
  pendingTasks.push_back(pos);
  return id;
}

//---------------------------------------------------------------------
template<class TaskWrapper>
void TerrainBasicImp<TaskWrapper>::remove_task(TerrainBase::TaskId tid)
{
  clean_task(tid);
}

//---------------------------------------------------------------------
template<class TaskWrapper>
void TerrainBasicImp<TaskWrapper>::cancel_task(const Object *obj)
{
  clean_task_for_obj(obj);
}

//---------------------------------------------------------------------
template<class TaskWrapper>
void TerrainBasicImp<TaskWrapper>::remove_obj(const Object *obj)
{
  // remove a task (if any) associated with this object
  clean_task_for_obj(obj);
  // remove objIsGoalInTaskId associations
  objIsGoalInTaskId.erase(obj);
}

//---------------------------------------------------------------------
template<class TaskWrapper>
void TerrainBasicImp<TaskWrapper>::add_obj(const Object * /*obj*/)
{
}

//---------------------------------------------------------------------
template<class TaskWrapper>
void TerrainBasicImp<TaskWrapper>::update_obj(const Object * /*obj*/)
{
}

//---------------------------------------------------------------------
template<class TaskWrapper>
void TerrainBasicImp<TaskWrapper>::add_segments(const Vector<TerrainBase::Segment> &/*segments*/)
{
}

//---------------------------------------------------------------------
template<class TaskWrapper>
void TerrainBasicImp<TaskWrapper>::clean_task_for_obj(const Object *obj)
{
  Obj2TaskId::iterator o2tiIt = obj2taskId.find(obj);
  if( o2tiIt == obj2taskId.end() )
    return;

  TerrainBase::TaskId taskId = o2tiIt->second;

  typename TaskId2Task::iterator ti2tIt = taskId2task.find(taskId);

  assert(ti2tIt != taskId2task.end());

  // if this is the only object of the task, erase the entire task
  if( ti2tIt->second->task.objs.size() <= 1 ) {
    eraseObjIsGoalFor(ti2tIt);
    eraseFromPending(ti2tIt->second);
    eraseFromFailed(ti2tIt->second);
    tasks.erase(ti2tIt->second);
    taskId2task.erase(ti2tIt);

  // else, remove the object from the task's list of objects
  } else {
    ti2tIt->second->task.objs.erase(obj);
  }

  // remove the obj2TaskId association
  obj2taskId.erase(o2tiIt);
}

//---------------------------------------------------------------------
template<class TaskWrapper>
void TerrainBasicImp<TaskWrapper>::clean_task(TerrainBase::TaskId task_id)
{
  typename TaskId2Task::iterator ti2tIt = taskId2task.find(task_id); 

  if( ti2tIt == taskId2task.end() ){
    std::cerr << "Tried to clean a task that we don't know about\n";
    return;
  }

  //  TaskQueue::iterator it = pendingTasks.begin(), end = pendingTasks.end();
  //  for (; it != end; ++it);
  //#endif   

  // remove obj2TaskId associations
  std::set<const Object*>::iterator objIt = ti2tIt->second->task.objs.begin();
  std::set<const Object*>::iterator end = ti2tIt->second->task.objs.end();
  //  FORALL (ti2tIt->second->task.objs, objIt) {
  for (; objIt != end; ++objIt) {
    obj2taskId.erase(*objIt);
  }

  // remove objIsGoalInTaskId associations
  eraseObjIsGoalFor(ti2tIt);

  // remove the task from the pending queue, if it's there
  eraseFromPending(ti2tIt->second);
 
  eraseFromFailed(ti2tIt->second);

  // (find and) remove the task
  tasks.erase(ti2tIt->second);

  // remove the taskId2task association
  taskId2task.erase(ti2tIt);
}

//---------------------------------------------------------------------
template<class TaskWrapper>
void TerrainBasicImp<TaskWrapper>::eraseFromPending(const TIter& iter)
{
#if GCC
  FORALL (pendingTasks, it) {
#else
  typename TaskQueue::iterator it = pendingTasks.begin(), end = pendingTasks.end();
  for (; it != end; ++it) {
#endif    
    if(*it == iter) {
      pendingTasks.erase(it);
      break;
    }
  }
}

//---------------------------------------------------------------------
template<class TaskWrapper>
void TerrainBasicImp<TaskWrapper>::eraseFromFailed(const TIter& iter)
{
#if GCC
  FORALL (failedTasks, it) {
#else
  typename TaskQueue::iterator it = failedTasks.begin(), end = failedTasks.end();
  for (; it != end; ++it) {
#endif    
    if(*it == iter) {
      failedTasks.erase(it);
      break;
    }
  }
}



template<class TaskWrapper>
void TerrainBasicImp<TaskWrapper>::eraseObjIsGoalFor(const typename TaskId2Task::iterator& ti2tIt)
{
  // shorthand
  typedef ObjIsGoalInTaskId::iterator OGIT;

  // If this task has an object as goal
  if( ti2tIt->second->task.goal.target == TerrainBase::Goal::OBJ ) {
    // find all associations from the goal_obj to tasks
    std::pair<OGIT,OGIT> range = objIsGoalInTaskId.equal_range(ti2tIt->second->task.goal.obj);
    // remove the one association that refers to the task we're cleaning
    for(OGIT i = range.first ; i != range.second ; i++ ) {
      if( i->second == ti2tIt->first ) {
        objIsGoalInTaskId.erase(i);
        break;
      }
    }
  }
}

#endif